Configuring application connector settings |
proiv dashboard |
Licensing Configuration
To set the Licensing configuration, on the Application Connector Settings tab, expand Licensing.
The configuration page appears with default
settings.
Modify the configuration as required. The following table describes the fields that can be configured.
Field Name |
Description |
Host |
The host name of the licence server. |
Port |
The port number of the licence server. The Licence Server accepts requests from PROIV components on this port. The default port number is 5439. This can be altered to avoid port clashes. |
Serial Number |
The serial number that controls which licence pool is used. It is a group identifier which uniquely identifies a licence on a server. |
Acquisition Period |
The maximum wait time (in seconds) to acquire a licence on startup. The default value is 30 seconds. |
Retry Period |
The maximum interval (in seconds) between licence acquisition requests. The default value is 2 seconds. |
Gateway Configuration
To set the Gateway configuration, on the Application Connector Settings tab, expand Gateway.
The configuration page appears with default settings.
Modify the configuration as required. The following table describes the fields that can be configured.
Field Name |
Description |
Listen Port |
The port that the Gateway server listens on for connections. The default port is the two digit current version (as found from &$@~PROPATH) suffixed with '835'. |
Maximum Gateway Sessions |
The maximum number of simultaneous connections that the Gateway server can support. This sets a resource limit on the use of this Gateway server. If another attempt is made to use this Gateway server after the limit is reached, the user will get an error message and a message will be put in the general log. This must be greater than 0 and 20 is a good starting value. The default number is 5. |
Virtual Machine Settings |
|
Port |
The port used to connect to the virtual machine on Windows machine. For Unix platforms, this is the port used by the kernel to connect to the gateway. The default port number is the two digit current version (as found from &$@~PROPATH) suffixed with '833'. |
Connection Mode |
Available only for Unix based systems. A dropdown list allows selection of the mode to be used to connect the kernel to the gateway. Network: gives the option to set a host name and port number for the connection to the PROIV VM. Process: displays the command path and parameter fields to make an executable connection. |
Host Name |
Name or IP address of the machine running the PROIV server process. For Unix network connections. |
Host Port |
Port number for Unix network connections. |
Initial VMs |
The number of Virtual Machines to start up ready for Gateway server connections. This creates a pool of Virtual Machines that are ready and waiting for gateway server connections and this improves the response time at the expense of resources. The value must greater than 0 and must be less than the Maximum VMs value. The default number is 1. |
Maximum VMs |
The maximum number of Virtual Machines that this Gateway server allows. This sets a resource limit on the use of this Gateway Server. If another attempt is made to use this Gateway Server after the limit is reached, an error message appears and a message is put in the general log. The value must be greater than 0 and is constrained by your number of Gateway Licences. The default value is 5. |
Timeouts |
|
Startup Timeout |
For Unix platforms, this is the maximum number of seconds to wait for a Virtual Machine to start. For Windows platforms, this is the maximum number of seconds to wait for a successful connection to be made to a Virtual Machine via the Virtual Machine service. This must be greater than 0. The default time is set to 60 seconds. |
Idle Timeout |
The maximum number of seconds a Virtual Machine can remain idle before the connection is closed. This must be greater than 0. The default value is 60. |
Read Select Timeout |
The number of milliseconds between read selects. Entering a value in this field configures the read_select_timeout parameter, which sets the PROIV Gateway's maximum wait time when it attempts to retrieve (read) data through NIO (Non-blocking I/O) data transfers before timing out and returning a 'Kernel not available' error message. The default setting is sufficient for many java-dependent applications that use NIO buffers. However, if other processes are consuming resources that are resulting in frequent read select timeouts, then increasing the value reduces the CPU load (that is, fewer read NIO buffer retries). Default value is 10 milliseconds. The maximum value is 1000 milliseconds. |
Response Timeout |
The maximum number of seconds to wait for a response from the Virtual Machine before timing out the operation. Note: This needs to be larger than the time taken for the slowest Task in your PROIV application. This must be greater than 0 and the default value is 60. |
Queuing |
|
Max Queue Size |
The maximum number of queued requests for sessions awaiting a free kernel. When the number of requests exceeds the number of available kernels, you can try increasing the maximum number of available kernels in the Maximum VMs field. This number is constrained by the number of Gateway licences that you have. Default is 100. |
Max Queue Wait Time |
The time in milliseconds that a request will be queued before getting a 'Virtual Machine not available' response. When the message displays, the request is removed from the queue and an error message is sent to the requestor. The default time is set to 1000 milliseconds. |
Authentication Model |
The JAVA class to be used for user authentication. "Default" is the selected model. When "JAAS" is selected, set values for Login Cache Timeout and Login Cache Size. Login Cache Timeout - The number of seconds that an authenticated user name/password will be regarded as valid without retrying the actual authentication. Note: The default time is set to '0' seconds to force each authentication request to be carried out. A good starting value is 3600. Login Cache Size - The maximum size of the cache containing authenticated user name/password combinations. Note: The default size is 2048. |
Web Services Configuration
To set the Web Services configuration, on the Application Connector Settings tab, expand Web Services.
The configuration page appears with default settings.
To configure PROIV connector, expand Connectors.
The PROIV connector appears by default. To add a new connector, click Connectors and then click New.
Click PROIV Connector to view the configuration. The following table describes the fields that can be configured.
Field Name |
Description |
Name |
An unique name to identify the connector. |
Description |
The description of the connector. |
Enabled |
The slider is turned ON by default, indicates the connector is enabled. |
CODIV |
The company or division code required to access the PROIV application. |
Operator ID |
The operator ID required to access the PROIV application. |
Operator Password |
The operator password required to access the PROIV application. |
Encoding |
The encoding used for data transfers. The default is UTF-8. |
To delete a connector, click Connectors and then click Delete button next to the connector that you wanted to delete.
The connector is deleted.
SOAP Services Configuration
To configure SOAP Services, on the Application Connector Settings tab, expand Web Services and then Soap Services.
The Demo
Web Service appears by default. To add a new SOAP service, click Soap Services and then click New.
To import an existing SOAP service, click Soap Services and then click Import.
Click Demo Web Service to view the configuration. The following table describes the fields that can be configured.
Field Name |
Description |
Name |
An unique name to identify the web service. |
Alias |
An alias name. |
Description |
The description of the web service. |
Enabled |
Turn ON the slider to enable the web service. The default value is set to True. |
Expand FunctionsFunctions to view the list of existing functions for Demo Web Service. To add a new function, click Functions and then click New. The following table describes the fields that can be configured.
The functions of a web service are the actions that the external application can execute. For a PROIV connector this is a Task, for a Java connector this is a method. A web service can have as many functions as you require and these can use any number of connectors.
Connector |
Select PROIV connector to establish a connection between the SOAP web service and an application. |
Name |
An unique name to identify the function. |
Alias |
An alias name. |
Description |
A simple description of the web service. |
Expand Input Parameters.
The existing parameters are displayed. To add a parameter, click Input Parameters and then click New.
The following table describes the fields that can be configured.
Name |
An unique name to identify the input parameter. |
Alias |
An alias name of the parameter. |
Description |
A simple description of the input parameter. |
Type |
The data type of the parameter, for example String. |
Min Length |
Appears for type 'Array'. Enter the minimum length of the parameter. |
Max Length |
Appears for type 'Array'. Enter the maximum length of the parameter. |
Expand Output Parameters.
The existing reports are displayed. To add a new parameter, click Output Parameters and then click New.
The following table describes the fields that can be configured.
Name |
An unique name to identify the output parameter. |
Alias |
An alias name of the parameter. |
Description |
A simple description of the output parameter. |
Type |
The data type of the parameter, for example String. |
Min Length |
Appears for type 'Array'. Enter the minimum length of the parameter. |
Max Length |
Appears for type 'Array'. Enter the maximum length of the parameter. |
Deleting Functions/Parameters - Select the function or parameter you wanted to delete and click Delete.
The function or parameter
is deleted without any confirmation dialog.
RESTful Configuration Settings
The following configuration is common and are applicable to all REST services.
Restful Maximum Request Size |
The maximum permissible size of the RESTful request object (MB) |
Options Require Authorization |
Authorization is the verification that the connection attempt is allowed. Should Options requests be protected by authorization |
Asynchronous Expire Time |
Time in seconds that asynchronous responses will remain available for collection. This configuration will help you to cancel an asynchronous operation after specified duration. |
Production Error Reporting |
The slider is turned ON by default, indicates that minimal details will be reported in error responses. Turn OFF the slider to enable a more detailed report in the response body. |
Restful Services
To configure RESTful Web ServiceRESTful Web Service configuration, on the Application Connector Settings tab
, expand Web Services and then RESTful Services.
The PROIV Demo Service appears by default. To add a new RESTful service, click RESTful Services and then click New.
There are two parts in a RESTful Web Service, the server and the client. PROIV can act as a client or a server but the Restful Service Definition only relates to PROIV as a server.
As a Server, the RESTful Service Definition holds server information that tells PROIV about the details of the protocol that is used (HTTP/HTTPS), any security information required (CORS and Security), the HTTP URL which is used (Connector and Path), the HTTP method which is used (Method) and the PROIV Task to call (Task). When a RESTful Web Service is enabled, PROIV uses this information and creates a server for the RESTful Service.
As a Client, the RESTful Service Definition holds client information for Code Generation feature to produce a library that can be used to call a RESTful Service. The library can be either PHP or Objective-C. The client information in the RESTful Service Definition is the protocol that is used (HTTP/HTTPS), the HTTP URL which is used (Connector and Path), the HTTP method which is used (Method), the request parameters which are required (Parameters and Body), the response codes which are expected (Status Code) and the response data that is expected (Schema).
Click RESTful Service to view the configuration. The following table describes the fields that can be configured for PROIV Demo Service or a new RESTful service.
RESTful Web Service Definition |
|
ID |
An internal identifier of web service. |
Name |
An unique name that identifies the RESTful Service. |
Description |
The description of the web service. |
Enabled |
The slider is turned ON to indicate that the service is enabled. If this is not set then the service is not available. |
Connector |
Select the required service connector from the list of the connectors defined in the Web Services. In case you have no connectors defined you will not be able to select a connector for the service. Refer to Connector Configuration for more information. |
CORS |
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. |
Exposed Headers |
The expose header name for the service to expose in response to any CORS service request; in case of multiple expose headers, separate the headers with a comma. The exposed headers will be returned in the response header ?Access-Control-Expose-Headers? for CORS simple requests. Currently, the PROIV REST code does not use any exposed headers for the service; however, by using expose headers - any calls to the service will let the caller know what headers are being used so this should only be used to expose ?public? information. There is no verification for these headers so their presence or absence will not cause any error status. |
Max Age |
The number of seconds that a CORS pre-flight request can cache its results before it needs to repeat the pre-flight request. This number is returned in the response header ?Access-Control-Max-Age? for a pre-flight request. |
Protocol |
The protocol used for the service can be HTTP, HTTPS or both but you must have at least one protocol selected. |
Request Headers |
The request header name for the service to accept; in case of multiple headers, separate the headers with a comma. A request 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. 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 Responses. 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. |
Credential Support |
Signifies that the service supports user credentials (security id/secret/task based authentication). Turn ON the slider to enable the credential support and configure security details. |
Security Id |
The security id. Setting the security id enables HTTP access security on the service. The server sends the text in this field to the client requesting the service and the client needs to respond with the security secret specified in the next field. |
Secret |
The secret text that the HTTP client needs to respond with if there is a security id. If there is no security id then this field is ignored. |
Expand Paths and then click New to add a path. Use the following table to configure the values.
Paths |
A service can have any number of paths defined. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Path |
Enter the name of the path. 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. When you create a new path it behaves as ?undefined? value and this is not a valid value and so gets highlighted by turning pink. A path can be deleted by clicking on the ? image to the right of the path. A path contents can be hidden and shown by clicking on the up or down arrow image on the right of the path. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Method |
By default, a list of methods (Post, Put, Patch, Get and Delete) along with its corresponding task is displayed. Each path can have up to five methods (Post, Put, Patch, Get and Delete) and you can not have duplicate methods in a path. A path must have at least one method so one will be automatically created when you create a new path. You can create a new method for a path by clicking on the Paths and then click New. A method can be deleted by clicking on the Delete button to the right of the method, but as there must be at least one method you can not delete a method if it is the only method in the path. The method contents can be hidden and shown by clicking on the up or down arrow image on the right of the method. Expand Methods and configure the methodsmethods as per the description mentioned in the table. For published RESTful Web Services, you must map the PROIV task to an incoming HTTP/S request. A published RESTful Web Service executes the task, by matching the URL path and HTTP/S methods. The mapping is done using the path of the incoming URL (server and port) and the HTTP/S methods (POST, PUT, PATCH, GET and DELETE). Additionally, partial matches can happen when a URL contains components that do not map to the exact name. For example, a mapping of ?abc? would match a URL of "abcdef" and equally "/abc123" and also "abc/def". You can select the required connector and set an authentication Challenge Response (Server issues a challenge and the Client sends a response) to connect to the gateway. When an incoming RESTful Service Request has a match in its path and its method then the task for the Published RESTful Web Service is called to get the response. HTTP Methods (POST, PUT, PATCH, GET, DELETE) The HTTP methods in the non-error path, returns a representation in XML or JSON and an HTTP response code of 200 (OK). In an error case, it most often returns a 404 (NOT FOUND) or 400 (BAD REQUEST). GET In general, the HTTP GET method request is used to read data. The resource identifiers in GET method are communicated with URL or Header parameters and do not have a request body. PUT, POST and PATCH Use PUT when you can update a resource completely through a specific resource. For instance, if you know that an article resides at http://sample.org/article/1234, you can PUT a new resource representation of this article directly through a PUT on this URL. If you do not know the actual resource location, for instance, when you add a new article, and do not have any idea to store it, you can POST it to an URL, and the server decides the actual URL. However, when you know the new resource location, you can use PUT again to update the existing item. The PUT method requests that the enclosed entity be stored under the supplied Request-URL. If the Request-URL refers to an already existing resource, the enclosed entity SHOULD be considered as a modified version of the one residing on the origin server. If the Request-URL does not point to an existing resource, and that URL is capable of being defined as a new resource by the requesting user agent, the origin server can create the resource with that URL". The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URL in the Request-Line. The PATCH method is similar to PUT but allows for the update of part of the endpoint resource. PUT replaces the complete resource with the body content. PATCH can have partial modifications and will apply them to the resource identified by the Request-URL in the Request-Line. DELETE DELETE is used to delete a resource identified by the information which is contained in the request. Additional Information on Sending RESTful Web Services parameters into PROIVPROIV supports the following ways to send the data or parameters through the RESTful Web Services Server.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Post |
To configure a POST method, refer to Configuration parameters of a Method section. You can add any number of parameters and responses as per your business requirement. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Put |
To configure a PUT method, refer to Configuration parameters of a Method section. You can add any number of parameters and responses as per your business requirement. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Patch |
To configure a PATCH method, refer to Configuration parameters of a Method section. You can add any number of parameters and responses as per your business requirement. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Get |
To configure a GET method, refer to Configuration parameters of a Method section. You can add any number of parameters and responses as per your business requirement. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Delete |
To configure a DELETE method, refer to Configuration parameters of a Method section. You can add any number of parameters and responses as per your business requirement. |
Set the configuration for the selected method using the following table:
Task |
A RESTful service needs a PROIV task to perform the service action and each method may have a separate task. You can also use the same task on multiple methods or paths. Enter the task name that is available in the PROIV defined by the service connector. |
Description |
Text that describes this service, path, and method. |
Body |
Signifies the body schema for this service path and method. 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 the 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. For more information, click PROIV Demo Service and look at the values that are configured for the methods. |
Content-type |
Select the content of the method. Examples are text/plain, application/json, and application/xml. |
Response |
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. |
Status Code |
A response is defined by its HTTP status code which is a number (For example, 200 is the OK status). You can create a new response by clicking on the New button. A response can be deleted by clicking on the Delete button to the right in the list. A response status consists of a description (any text) and a response body schema. The schema field defines a JSON schema in the same way as the request body. |
Parameters |
A service method requires parameters when it is called. To add a new parameter for a method, click Parameters and then click New.
Parameters with the same name can be defined but only unique names are sent to the service so only one of the parameters with the same name can be used. The order of the parameters has no significance. Note: You need not to define parameters for a method. |
To Import or Export Defintions
To export a RESTful service definition, click the RESTful Services folder. In the list of services click the Export button next to the service to be exported. A file
save dialog will be displayed allowing the path of the export file to be specified. Files will save with extension .rwsd.
To import a RESTful service definition, click the RESTful Services folder and then click the Import button. A file open dialog will be displayed allowing the
path of the import file (with file extension .rwsd or .rsd) to be selected. (Note that RESTful services exported from PROIV Version 8 can be imported from files with extension .rsd)
When importing a RESTful service definition, there is a possibility that either the RESTful service definition name or one or more of the paths will conflict with an existing definition name or path. The clash may be in the current configuration
or in any other saved configuration. As names must be unique you will need to decide how to process any duplication in the dat you are importing.
The Import Settings button allows you to select strategies for handling duplicate names. A dialog will be displayed allowing selection of import strategies individually for the service definition
and the paths. Dropdown lists give the following options.
Replace - The existing object with the duplicate name will be replaced by the imported one.
Rename - The imported object will be renamed. The renaming will simply add a number to the original to give a unique name.
Refuse - Do not import the object having the duplicate name.
To Import or Export Paths
To export a RESTful service path, expand the services tree and select Paths under the service. From the lists of paths click the Export button for the path to be exported. A file save dialog will be displayed allowing the path of the export file (with file extension .rwsp) to be specified.Replace - The existing path with the duplicate name will be replaced by the imported one.
Rename - The imported path will be renamed. The renaming will simply add a number to the original to give a unique name.
Refuse - Do not import the path having the duplicate name.
Related Topics
Topic ID: 830001