application connector operations
proiv dashboard
|
application connector operations |
proiv dashboard |
|
RESTful Web Services Demo
The demo uses the Restful Web Service definition PROIV Demo Service and makes call to an example PROIV crm database.
To make calls to the web service select the restful method and click the Send button.
To set the RESTful Web Services Demo configuration, do the following:
On the Application Connector Operations
page, expand RESTful Web Services
Demo.
The Application Connector operations page appears.
Enter the configuration as required. The following table describes the fields that can be configured.
Field Name |
Description |
|||||||||||||||||||||||||||
Options |
||||||||||||||||||||||||||||
Authorization |
||||||||||||||||||||||||||||
Security id |
Enter the security id. Setting the security id enables HTTP access security on the service. The server sends the text to the client requesting the service, and the client needs to respond with the security secret specified in the next field. |
|||||||||||||||||||||||||||
Secret |
Enter the secret text that the HTTP client needs to respond with if there is a security id. If there is no security id, this field is ignored. |
|||||||||||||||||||||||||||
CORS |
||||||||||||||||||||||||||||
Enable CORS |
Cross-origin resource sharing (CORSCORS) defines a way for client web applications that are loaded in one domain to interact with resources in a different domain. CORS (Cross-Origin Resource Sharing) Abbreviation for Cross-Origin Resource Sharing. This is a mechanism that allows a restricted resource on a web page to be requested from another domain outside the domain from which the resource originated. The CORS field also holds the comma separated list of origins that are acceptable to the service. If you want to accept requests with no origin, then the CORS field must be empty (that is, CORS is turned off). The CORS field holds a list of origins and if the field contains at least one origin (* is counted as an origin) then the request must contain an ‘Origin’ header that matches one of the origins in the field. If it does not, then the request will be rejected with an error status (403 – Forbidden). An origin can be either a protocol/host/port triple or a GUID (Globally Unique Identifier). If the origin is triple (most likely) then it can be defined in the CORS field as a full triple, without the protocol or without the port. The host must always be fully defined and no wild cards are allowed in the host name. An origin defined in the CORS field without a protocol
will use whatever protocols are defined for the service. The protocol defined for a service always overrides any protocol defined in an origin in the CORS field when looking for a match. For example, an origin of ‘http://myhost.com:80’ will never match if the service does not have the http protocol enabled even if the origin supplied in the request is identical. An origin defined in the CORS field without a port will use the default port defined for the service to do a match. For http that is ‘80’ and for https that is ‘443’. It is acceptable to define an origin in the CORS field with just a host name. In this case it will attempt to match request origins using all the protocols defined for the service and the default port defined for the protocol. For more information on CORS, refer to https://www.w3.org/TR/cors/Type your drop-down text here. Turn ON the slider for Enable CORS to enable the service. If this is not set, the service is not available. If you set and save the service it might be auto disabled where a red indicator appears. Click the red indicator to view the message that explains the reason for being auto disabled. Note: If a REST service has
both CORS and authorization (security ID & secret) enabled,
the CORS Options request must include authorization. If this
is not required then authorization for an Options request
can be turned off by setting the servlet parameter 'restful_options_needs_authorization'
to 'false' in the WebServices web.xml file. |
|||||||||||||||||||||||||||
Headers |
Enter the request header name for the service to accept; in case of multiple headers, separate the headers with a comma. A request headerrequest header name defines a name that the service will accept in the request header called 'Access-Control-Request-Headers' for a CORS pre-flight request. The request headers that were accepted will be returned in the response header ‘Access-Control-Allow-Headers’ for the CORS pre-flight request. Request Header Properties The following table consists a list of properties that are available in the RESTfulRequestSSO. Some of these properties are defined by the calling client and may not be present in the RESTful request; hence marked as optional. To access these properties, use the getHdrParameter method on the RESTfulRequestSSO.
A service does not need to use any headers, hence the field can be left blank but if a CORS pre-flight request does specify headers in the ‘Access-Control-Request-Headers’ header, then these must be defined in this field or an error status will be returned as stated in the Failed Status ResponsesFailed Status Responses. Failed Status Responses The PROIV REST server will respond with a failed status code to any request that does not pass the CORS processing. These status code are defined below: 406 Not Accepted – This status code is returned if a CORS pre-flight request is received when CORS processing for the service is not turned on (that is the ‘CORS’ field in the service definition is empty). 403 Forbidden – This status code is returned for a number of CORS failures: • There is no ‘Origin’ header in a CORS pre-flight or simple request. • The origin specified in the ‘Origin’ header, in a CORS pre-flight or simple request, did not match any origin specified in the service definition ‘CORS’ field using the rules defined above. • There is no ‘Access-Control-Allow-Methods’ header in a CORS pre-flight request. 405 Method Not Allowed – The method specified in the ‘Access-Control-Allow-Methods’ header, in a CORS pre-flight request, is not one specified in the service definition. 417 Expectation Failed – One of the headers specified in the ‘Access-Control-Request-Headers’ header, in a CORS pre-flight request, was not defined in the ‘Req Headers’ field in the service definition. A response with a failed status code will also contain a ‘RWS_Error’ header that holds a string with a short explanation of the reason for failure. Note: The ‘Authorization’ header used by the PROIV REST server is automatically included in the list of acceptable request headers so does not need to be defined here. |
|||||||||||||||||||||||||||
Asynchronous |
||||||||||||||||||||||||||||
Asynchronous |
Turn ON the slider for AsynchronousAsynchronous to execute the REST service asynchronously. Asynchronous RESTful Web Service The request processing in PROIV works by default in a synchronous processing mode, which means when you invoke a web service, the invoking client application waits for the response to return before it can continue with its work. This model is typically sufficient for processing of requests for which the processing resource method execution takes a relatively short time. However, in cases where a service execution is known to take a long time to compute the result, server-side asynchronous processing model may be used. This helps the client application to continue its work and handle the response later on. In the Asynchronous model, the association between a service request processing thread and the PROIV kernel task is broken. Asynchronous REST services will start a new thread to access the PROIV Kernel and return a 202 (Accepted) response status immediately. The PROIV kernel processing thread continues in the same way as it does for synchronous REST services. To identify an Asynchronous REST service, the REST server looks for the request header property called ‘Operation-Type’ and if it has the value of ‘async’ then the service will be processed asynchronously. Any other values will cause the service to be processed synchronously. If the header is not present, then the service will be processed synchronously. After an Asynchronous service has started, the client can poll the server sending requests to ask for the status of the service. The returned response status will be 200 (OK) and the data status will be ‘In Progress’ until the service is complete. When the service is complete the returned response status will be 303 and the response header will contain a URL that will return the service result. There is no change in the definition of a PROIV REST service in order to run a service asynchronously. All currently defined REST services can be run synchronously or asynchronously. The following section diagrams describes the flow of synchronous and asynchronous REST calls:
Process flow for Synchronous REST web service request
Process flow for Asynchronous REST web service requestType your drop-down text here. |
|||||||||||||||||||||||||||
HTTP Request Method |
||||||||||||||||||||||||||||
Method |
Select a method. Refer to RESTful Web Service methods for more information. By default, GET method is selected. |
|||||||||||||||||||||||||||
Request Data |
Description |
Method Request |
||||||||||||||||||||||||||
ContactId |
Contact Id is mandatory except for POST and represents the unique indentifier of the contact created in the crm database. This has a maximum entry of 8 numeric characters. It is generated automatically for a new contact with next available number for the ContactIdId (POST) and is formatted with leading zeros e.g. '00000010'. |
PATCH, GET, PUT & DELETE |
||||||||||||||||||||||||||
ContactName |
Represents the full name of the contact created in the crm database and is free format text. Contact name is mandatory for a new contact and can be a maximum of 80 characters. |
POST & PUT |
||||||||||||||||||||||||||
ContactCompany |
Represents the company name of the contact created in the crm database and is free format text. Contact company is mandatory for a new contact and can be a maximum entry of 50 characters. |
POST & PUT |
||||||||||||||||||||||||||
ContactTitle |
Represents the title of the contact created in the crm database e.g. 'Ms' and is free format text. The title can be a maximum entry of 10 characters. |
POST & PUT |
||||||||||||||||||||||||||
ContactEmail |
Represents the email address of the contact created in the crm database and is free format text. This email address is mandatory for a new contact, if ContactPhone is left blank, and can be a maximum of 250 characters. Both ContactPhone and ContactEmail can be entered together if required. |
POST, PATCH & PUT |
||||||||||||||||||||||||||
ContactPhone |
Represents the company telephone number of the contact created in the crm database and is free format text. This phone number is mandatory for a new contact, if ContactEmail is left blank, and can be a maximum of 20 characters. Both ContactPhone and ContactEmail can be entered together is required. |
POST, PATCH & PUT |
||||||||||||||||||||||||||
ContactStatus |
Represents the status of the contact created in the crm database and is free format text and is validated against a table of valid statuses (CRMDemo_Status). Contact status is mandatory for a new contact and can be a maximum entry of 20 characters. Valid examples are 'Archive', 'Lead', 'Opportunity' and 'Won'. |
POST & PUT |
||||||||||||||||||||||||||
ContactProject |
Represents the project associated with the contact created in the crm database and is free format text. Contact project is mandatory for a new contact and can be a maximum entry of 50 characters. |
POST & PUT |
||||||||||||||||||||||||||
ContactDate |
Represents the date allocated to the contact created in the crm database and is formated 'YYYY/MM/DD'. Contact date is mandatory for a new contact. |
POST, PATCH & PUT |
||||||||||||||||||||||||||
NotesStatus |
Represents the status of the notes associated with a contact created in the crm database and is free format text. Notes status is optional and can be a maximum entry of 20 characters. Valid entries include 'Completed' and 'Pending'. |
POST |
||||||||||||||||||||||||||
NotesDescription |
Represents a description of the notes allocated to the contact created in the crm database. Contact description is mandatory and has a maximum entry of 20 characters. Valid entries include 'Demo', 'Follow up Email', 'Meeting' and 'Phone Call'. |
POST |
||||||||||||||||||||||||||
NoteIsToDoType |
Represents note is to do type allocated to the contact created in the crm database. Notes is to do type is mandatory for a new contact and is validated against a table of to do types (DEMOCRM_To_Do_Type). NotesToDoType is mandatory for a new contact and can be a maximum entry of 20 characters. Valid entries include 'Meeting' and 'Task'. |
POST |
||||||||||||||||||||||||||
NotesText |
Represents the notes associated with a contact created in the crm database and is free format text. Contact notes is mandatory for a new contact and can be a maximum entry of 250 characters. When a new note is added it is associated with the contact and has a unique note Id number genrated in the same format as contact Id. |
POST |
||||||||||||||||||||||||||
NotesToDueDueDate |
Represents the notes to do due date allocated to the a contact's notes created in the crm database and is formated 'YYYY/MM/DD'. Notes due date is optional. |
POST |
||||||||||||||||||||||||||
NoteIsToDo |
Represents notes is to do against a contact created in the crm database. Notes to do is true or false and defaults to true. |
POST |
||||||||||||||||||||||||||
NotesEntryDate |
Represents the date allocated to the a contact's notes created in the crm database and is formated 'YYYY/MM/DD'. Notes entry date is mandatory for a new contact. |
POST |
||||||||||||||||||||||||||
URL |
||||||||||||||||||||||||||||
Endpoint |
The URL is created automatically with the specified ContactId value. The URL is recognized by the server as a request for a RESTful Service. This can be any text but must start with "/". If you do not put "/" at the beginning, the "/" gets added automatically when the service is saved. Click Send to execute the REST call. |
|||||||||||||||||||||||||||
Response |
||||||||||||||||||||||||||||
Status |
The path is the last part of a URL that will be recognized by the server as a request for a RESTful Service. This can be any text but must start with "/". If you do not put "/" at the beginning, the "/" gets added automatically when the service is saved. |
|||||||||||||||||||||||||||
Response Body |
A service method may define the acceptable responses for a service call. You can create as many responses as you want and you do not have to define any responses. You
can define the body data for a service method which requires
request body data when it is called. Only methods of type
‘post’, ‘put’ or 'patch' can define a request body. This body field
defines a JSON schema for the request body content and this
schema will be used by the test panel and the client generation
tool to provide some checking that the request body has the
correct structure before a call to the service is performed. To help in schema generation you can enter an actual JSON object and click ‘{o}->{s}’ on the right of the field and it will convert your JSON object to a valid JSON schema. |
|||||||||||||||||||||||||||
You can test a RESTful web service only if it is saved as 'Enabled'. However, if the service is not enabled or has not yet been saved the test appears disabled.
Any Restful web services that have been defined in the configuration settings will be available for testing here once the configuration has been deployed.
As an example, to test the RESTful Web Services Demo configuration, do the following:
To test the RESTful Web Services CRM Demo configuration, do the following:
On the Application Connector Operations
page, expand RESTful Web Services
Test.
The PROIV CRM Demo Service section appears.
Field Name |
Description |
Use secure protocol |
Turn ON the slider to use secure protocol (HTTPS). If the slider is turned OFF, the service will use HTTP protocol. |
PATCH |
Enter the unique Contactid and type in any values that you want to change. You do not need to give values for every field when using patch. Click Test to test the service with the configured values. The response is displayed under the Response section with the response code and description as you have set in the PATCH method of RESTful Web Service configuration. |
POST |
Enter the values for the fields ContactTitle (mandatory), ContactName (mandatory), ContactPhone (mandatory if ContactEmail not entered), ContactEmail (mandatory if ContactPhone is not entered), ContactCompany (mandatory), CompanyAddress 1 to 4 (optional), CompanyPostcode (optional), ContactProject (mandatory), ContactStatus (mandatory) and ContactDate (mandatory in format 'YYYY/MM/DD'). Click Test to test the service with the configured values. The response is displayed under the Response section with the response code and description as you have set in the POST method of RESTful Web Service configuration. |
GET |
Enter the value for the field ContactId which is mandatory and is a unique identifier for CRM contact. Click Test to test the service with the configured contact id. The response is displayed under the Response section with the response code and description as you have set in the GET method of RESTful Web Service configuration. |
DELETE |
Currently unavailable. Enter the unique ContactID. Click Test to test the service with the configured values. The response is displayed under the Response section with the response code and description as you have set in the DELETE method of RESTful Web Service configuration. |
PUT |
Enter the values for the fields such as Contactid (mandatory for updating contact details), ContactTitle, ContactName, ContactPhone, ContactEmail, ContactCompany, ContactAddress 1-4 and CompanyPostcode with similar validation to POST. All mandatory fields are required for a new contact in PUT. Click Test to test the service with the configured values. It will update details if found for the Contactid or create a new entry if the Contactid does not exist. The response is displayed under the Response section with the response code and description as you have set in the PUT method of RESTful Web Service configuration. |
Set the configuration as required. The following table describes the fields that can be configured.
A web service definition basically consists of a name and one or more functions. These functions are the 'Endpoints' in the WSDL (Web Services Description Language) and define the application functionality that may be called by an external application.
A function first needs you to define a connector. This connector defines the instance of the application by connecting to a particular application server. So, for example, you may have a 'Live' and a 'Test' version of your PROIV application and have a connector for each one.
Once you have chosen a connector you can select a function from the list available for that connector. The function list is automatically generated by the web services application. It does this by connecting to the application and asking for the function list. As this can take some time it is only done the first time a connector is used. Subsequent uses of the connector display a cached list of functions.
When you select a function the web services application automatically builds a definition of the function so that it can be used as a WSDL Endpoint. This definition includes the input and output parameters with a name, type, description and size for each one. You can alter some of the parameter properties.
To set the SOAP Web Services Demo configuration, do the following:
On the Application Connector Operations
page, expand SOAP WSDL.
The SOAP services that are configured are displayed. The Demo Web Service
appears by default.
The following table describes the fields that helps use the service for the selected web service.
Field Name |
Description |
Use secure protocol |
Turn ON the slider to use secure protocol (HTTPS). If the slider is turned OFF, the service will use HTTP protocol. |
Endpoint |
The URL is created with the specified configuration settings. You can not change the URL as it s read-only. The URL is recognized by the server as a request for a SOAP Service. This can be any text but must start with "/". If you do not put "/" at the beginning, the "/" gets added automatically when the service is saved. |
|
The Web Services Description Language (WSDL) is a standard XML string that defines the functions available in a web service. |
Enter WSDL URL to get a web page. You
can use the URL to see the XML that is generated for the web
service when executed by a service client. |
Related Topics
Topic ID: 830005
