Configuring Application Connector Settings

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.

Field Name	Description
Listen Port	The port that the Gateway server listens on for connections. The default port is 10835.
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 10833.
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. If the host port is changed to a different port number to the virtual machine task port then a confirmation dialog will be displayed when the configuration is saved, asking whether the virtual machine task port should also be updated to the same number.
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.

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.

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.

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.

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.

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.

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.

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).

RESTful Web Service Definition
ID	An internal identifier of web service.
Name	An unique name that identifies the RESTful Service. Note: The name can be any text. However, you cannot have two services with the same name. If you save a service that has the same name as a service already saved on the server then its name will be changed to have [n] at the end (where n is a number).
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. Note: A PROIV Restful service only supports the http or https protocols; so origins defined with other protocols will never match. 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/
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.

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 PROIV

PROIV supports the following ways to send the data or parameters through the RESTful Web Services Server.

Mime Type		Get/Delete	Post/Put/Patch
Any	Url Parameters	header.parameters	header.parameters
	Headers	Put into the header object	Put into the header object
Application/www form URL encoded	Body Params	N/A	Promoted to header.parameters
	JSON Body	N/A	Put the JSON in the header.parameters. It is unlikely to be in a shape that makes any sense as URL encoded Name value pairs.
	XML Body	N/A	Put the JSON in the header.parameters. It is unlikely to be in a shape that makes any sense as URL encoded Name value pairs.
Application/JSON	JSON Body	N/A	JSON decoded to create the body object.
	BodyParams	N/A	Put in the stringBody.
	Non JSON Body	N/A	Put in the stringBody.
Application/xml	XML Body	N/A	XML converted to JSON and decoded to create the body object.
	Body Parameters	N/A	Put in the stringBody.
	Non XML Body	N/A	Put in the stringBody.
Text/html	Html Body	N/A	Put in the stringBody.
	Body Parameters	N/A	Put in the stringBody.
Text/Plain	Text Body	N/A	Put in the stringBody.
	Body Parameters	N/A	Put in the stringBody.

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.

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. A parameter contains a Name and Description . 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 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.

To import a RESTful service path, expand the services tree and select Paths under the service. Click the Import button. A file open dialog will be displayed allowing the path of the import file to be selected. Path exports are saved with an extension of .rwsp.

When importing a RESTful service path, there is a possibility that the RESTful service path may conflict with an existing path name. The clash may be in the current configuration or in any other saved configuration.