Support Generic WebService Connector
1. Overview
This connector provides a generic way for SAP IDM to interact with external systems. It can be configured to perform HTTP calls using a template dynamically filled with variable values. Because of the generic setup, there are a lot of configuration attributes that need to be set. The sections below have a detailed description of these and how to use them.
2. Usage
Like all connectors, there are 2 implemented Custom classes: com.fasers.idm.ic.generic.FromCustomSystem – for retrieving values from an external system com.fasers.idm.ic.generic.ToCustomSystem – to modify an external system (add/update/delete)
NB: In ToCustomSystem only modEntryCustom is implemented (addEntryCustom and deleteEntryCustom will throw an exception). This is because the generic implementation has no knowledge what kind of modification is taking place.
Put provided JAR file on the classpath of SAP IDM. Also make sure there is a folder on the classpath of IDM where you can place template files. Those will be available in the running SAP IDM without any restarts.
3. Attributes
3.1 System Attributes
There are some system attributes that should be supplied to setup the system. These will always be in the form of pass attributes. The following system attributes are supported:
| Required | Attribute name | Description | Value Type |
|---|---|---|---|
| Yes | SYSTEM.Name | A human readable name of the system to connect to | Free text |
| Yes (1) | SYSTEM.EndpointPrefix | The base URL where the system can be reached | HTTP(S) URL |
| Yes | SYSTEM.TemplateFolderPrefix | The base folder where the template files are stored in the classpath | Classpath entry, no whitespace (start with and separate folders with forward slash ‘/’) |
| Yes | SYSTEM.TemplateAttributePrefix | A prefix for all template attributes | Upper case string, without whitespace (cannot be ‘SYSTEM’, ‘REQUEST’ or ‘RESPONSE’) |
| No | SYSTEM.ProxyRequired | Whether or not a proxy should be used | The value ‘true’ for yes, any other value will be no |
| No | SYSTEM.ProxyHost | Hostname of the HTTP proxy to use | Hostname or IP address |
| No | SYSTEM.ProxyPort | Port of the HTTP proxy to use | Number in the normal port range |
| No (2) | SYSTEM.ProxyUsername | Username for the HTTP proxy to use | Free text |
| No (2) | SYSTEM.ProxyPassword | Password for the HTTP proxy to use | Free text |
| No | SYSTEM.BasicAuthRequired | Whether or not a basic authentication should be used | The value ‘true’ for yes, any other value will be no, defaults to ‘false’ |
| No (3) | SYSTEM.BasicAuthUsername | Username of the basic authentication | Free text |
| No (3) | SYSTEM.BasicAuthPassword | Password of the basic authentication | Free text |
| No | SYSTEM.LogMode | Defines the way logging is handled | Either ‘NORMAL’, ‘ALL_TO_ERROR’ or ‘SYSOUT’, defaults to ‘NORMAL’ |
(1) Is allowed to contain URL attributes in the form of {{URL.XXX}}, see section 3.3 for more information. (2) Required if SYSTEM.ProxyRequired is ‘true’ (3) Required if SYSTEM.BasicAuthRequired is ‘true’
3.2 Request Attributes
Request attributes are variables that differ per request and are needed to configure the request correctly, but are not present as values in the template. These will always be in the form of pass attributes. The following request attributes are supported:
| Required | Attribute name | Description | Value Type |
|---|---|---|---|
| No (1,2) | REQUEST.EndpointPath | The path to post the request to (after the SYSTEM.EndpointPrefix) | Path of a URL |
| Yes | REQUEST.HttpMethod | The HTTP method to use for the request | One of ‘GET’, ‘PUT’, ‘POST’, ‘DELETE’ or ‘PATCH’ |
| No (3) | REQUEST.ContentType | The content type to use for the request | A valid MIME type, see for this list for the most common ones |
| No (3) | REQUEST.TemplateFile | The filename of the template in the classpath (after the SYSTEM.TemplateFolderPrefix) | File name, no whitespace (can include a sub-path) |
| No (4) | REQUEST.TemplateAttributeNames | List of names of template attributes in this request | A list of strings, separated by ‘!!’ |
| No (5) | REQUEST.HeaderAttributeNames | List of names of custom header names | A list of strings, separated by ‘!!’ |
| No (6) | REQUEST.HEADER.XXX | Custom header name (XXX) and value | Free text |
(1) Can be empty in case the SYSTEM.EndpointPrefix is already the full URL (like for SOAP services)
(2) Is allowed to contain URL attributes in the form of {{URL.XXX}}, see section 3.3 for more information.
(3) Required for methods ‘PUT’, ‘POST’ and ‘PATCH’
(4) Required in case of FromCustomSystem (unless template contains no attributes)
(5) Only needed in case of FromCustomSystem and the need to add extra headers to the request (whole names like REQUEST.HEADER.XXX should be used)
(6) Extra headers will be added with the value for ‘XXX’ as key and the attribute value as value
3.3 URL Attributes
URL attributes are key/value pairs that should be used to populate the URL, replacing the {{URL.XXX}} placeholders present in the URL. These key/values can only be supplied in case of ToCustomSystem. URL attributes are NOT supported in FromCustomSystem. A URL attribute name must be in the form of URL.XXX, where XXX is a custom name to identify the variable. The name should not contain any whitespace and is advised to be in CamelCase form. A URL attribute value can be any free text string that is complient with URL restriction. NB: The URL attribute name should always include the ‘URL.’ prefix, to be able to easily filter them out of all supplied attributes.
3.4 Template Attributes
Template attributes are key/value pairs that should be used to populate the template. These key/values are supplied by either pass attributes (in case of FromCustomSystem) or in the attribute mapping (in case of ToCustomSystem). A template attribute name consists of the upper case prefix, then a dot ‘.’, followed by the actual name. The actual name should not contain any whitespace and is advised to be in CamelCase form. A template attribute value can be any free text string. NB: The template attribute name in the request should always include the template attribute prefix (so also in case of the list in REQUEST.TemplateAttributeNames), to be able to easily filter them out of all supplied attributes.
3.5 HMAC – Hashing & Signing
As the last step in building the request, it might be needed to perform hashing & signing of the request as part of security requirements. The connector supports HMAC for this as that is the mostly used algorithm in this context. The HMAC input, hash algorithm and key can be configured, as well as the header to put the signed result in. The output bytes of the HMAC algorithm will be converted to a HEX string and put in the configured header. The key/value pairs will always be in the form of pass attributes. The following HMAC attributes are supported:
| Required | Attribute name | Description | Value Type |
|---|---|---|---|
| No | HMAC.Required | Whether or not to perform HMAC hashing & signing | The value ‘true’ for yes, any other value will be no, defaults to ‘false’ |
| No (1) | HMAC.Input | The HMAC input | Free text (2) |
| No (1) | HMAC.HashAlgorithm | The hash algorithm to use | Either ‘MD5’, ‘SHA1’ or ‘SHA256’ (‘SHA384’ and ‘SHA512’ can be tried but are not supported by all JVM’s) |
| No (1) | HMAC.Key | The HMAC secret key | Free text (3) |
| No (1) | HMAC.ResultHeader | Name of the header to put the HMAC hashing & signing result in | Free text |
(1) Required when HMAC.Required is ‘true’
(2) The HMAC input can contain the following placeholders: {{NEWLINE}} for a newline: ‘\n’, {{BODY}} for the request body and {{VALUE_OF_HEADER(XXX)}} for the value of header XXX (where XXX is a request header)
(3) Although the key can be any length larger than 0, longer is of course better for security reasons. Recommended is about 32 characters (= 256 bits).
3.6 Response Attributes
Response attributes define how to handle the response. These will always be in the form of pass attributes . There are 2 different scenario’s: A. You just want to validate if the response is as expected (in case of ToCustomSystem) B. You want to actually get values reported back to IDM (in case of FromCustomSystem) In case of scenario B you have to choose an option for A as well
| Required | Attribute name | Description | Value Type |
|---|---|---|---|
| Yes | RESPONSE.ValidationMode | Defines how the response from the system should be validated (1) | Either ‘NONE’, ‘CONTAINS’, ‘REGEX’, ‘XPATH’ or ‘JSONPATH’ |
| No (2) | RESPONSE.ValidationValue | The value to be used for the validation mode | Free text (3) |
| No (4) | RESPONSE.NumberOfResultProperties | The amount of properties to be returned | A number, 0 or higher |
| No (5) | RESPONSE.ResultPropertyXName (5) | The name of result property X | Free text |
| No (5) | RESPONSE.ResultPropertyXQueryMode (5) | The query mode of result property X | Either ‘REGEX’, ‘XPATH’ or ‘JSONPATH’ |
| No (5) | RESPONSE.ResultPropertyXQueryValue (5) | The query value of result property X | Free text (3) |
(1) The validation consists of checking if the evaluation gives a non-empty result (e.g. contains = true or XPath has ‘hits’). Of course the content type of the response must match the validation mode, so an XPATH mode can only be applied to an XML response and a JSONPATH mode can only be applied to a JSON response.
(2) Required for all validation modes but ‘NONE’
(3) It should match with the validation/query mode (valid regex, xpath or jsonpath expresssion)
(4) Required in case of FromCustomSystem
(5) ResultPropertyXName, ResultPropertyXQueryMode, ResultPropertyXQueryValue should be present for all numbers 1 to RESPONSE.NumberOfResultProperties. Replace the X with the next number and repeat for every result property.
4. Context Variables
The generic connector can also ‘return’ a result when using ToCustomSystem. Traditionally, there is no way to provide values back to SAP, because there is no return type like with FromCustomSystem. The solution is using context variables that can be given a value inside the connector and later read from SAP. This can be useful to for instance grab the value of a created id or other type of information that is present in the response from a call to the external system.
Currently the generic connector allows for 1 value to be set in the context variables. The name of this variable will always be RESPONSE.ExtractedResult and it’s type will always be String. It’s value will be set according to the validation done by the ValidationMode and ValidationValue, see section 3.6: – In case of ‘NONE’, no context value will be set – In case of ‘CONTAINS’ the value will be the same as the ValidationValue – In case of ‘REGEX’, the value will be the first matched pattern in the response – In case of ‘XPATH’, the value will be the text value of the first matched element in the response – In case of JSONPATH’, the value will be the value of the first matched item in the response
So please note that in case of multiple matches, only the value of the first match will be put in the context variable.
5. Examples
5.1 ToCustomSystem: POST of an plain text document
| System Attribute | Value |
|---|---|
| SYSTEM.Name | Example |
| SYSTEM.EndpointPrefix | https://www.example.com/api/ |
| SYSTEM.TemplateFolderPrefix | /connectors/example/templates/ |
| SYSTEM.TemplateAttributePrefix | EXAMPLE |
| Request Attribute | Value |
| REQUEST.EndpointPath | documents |
| REQUEST.HttpMethod | POST |
| REQUEST.ContentType | text/plain |
| REQUEST.TemplateFile | new-document.txt |
| Template Attribute | Value |
| EXAMPLE.Variable1 | Value1 |
| EXAMPLE.Variable2 | Value2 |
| Response Attribute | Value |
| RESPONSE.ValidationMode | CONTAINS |
| RESPONSE.ValidationValue | success |
5.2 ToCustomSystem: DELETE
| System Attribute | Value |
|---|---|
| SYSTEM.Name | Example |
| SYSTEM.EndpointPrefix | https://www.example.com/api/ |
| SYSTEM.TemplateFolderPrefix | /connectors/example/templates/ |
| SYSTEM.TemplateAttributePrefix | EXAMPLE |
| Request Attribute | Value |
| REQUEST.EndpointPath | documents/1 |
| REQUEST.HttpMethod | DELETE |
| Response Attribute | Value |
| RESPONSE.ValidationMode | CONTAINS |
| RESPONSE.ValidationValue | deleted |
5.3 FromCustomSystem: GET of a json document (REST service)
| System Attribute | Value |
|---|---|
| SYSTEM.Name | Example |
| SYSTEM.EndpointPrefix | https://www.example.com/api/ |
| SYSTEM.TemplateFolderPrefix | /connectors/example/templates/ |
| SYSTEM.TemplateAttributePrefix | EXAMPLE |
| Request Attribute | Value |
| REQUEST.EndpointPath | books |
| REQUEST.HttpMethod | GET |
| Response Attribute | Value |
| RESPONSE.ValidationMode | REGEX |
| RESPONSE.ValidationValue | [0-9]+ |
| RESPONSE.NumberOfResultProperties | 1 |
| RESPONSE.ResultProperty1Name | TheAuthor |
| RESPONSE.ResultProperty1QueryMode | JSONPATH |
| RESPONSE.ResultProperty1QueryValue | $.books[1].author |
5.4 FromCustomSystem: POST of an XML document (SOAP Service)
| System Attribute | Value |
|---|---|
| SYSTEM.Name | Example |
| SYSTEM.EndpointPrefix | https://www.example.com/api/service |
| SYSTEM.TemplateFolderPrefix | /connectors/example/templates/ |
| SYSTEM.TemplateAttributePrefix | EXAMPLE |
| Request Attribute | Value |
| REQUEST.EndpointPath | |
| REQUEST.HttpMethod | POST |
| REQUEST.ContentType | text/xml |
| REQUEST.TemplateFile | get-books.xml |
| REQUEST.TemplateAttributeNames | EXAMPLE.Year!!EXAMPLE.InStock |
| Template Attribute | Value |
| EXAMPLE.Year | 2017 |
| EXAMPLE.InStock | true |
| Response Attribute | Value |
| RESPONSE.ValidationMode | CONTAINS |
| RESPONSE.ValidationValue | <result> |
| RESPONSE.NumberOfResultProperties | 2 |
| RESPONSE.ResultProperty1Name | TheAuthor |
| RESPONSE.ResultProperty1QueryMode | XPATH |
| RESPONSE.ResultProperty1QueryValue | /books/book/author |
| RESPONSE.ResultProperty2Name | TheTitle |
| RESPONSE.ResultProperty2QueryMode | XPATH |
| RESPONSE.ResultProperty2QueryValue | /books/book/title |
5.5 ToCustomSystem: POST, using URL attributes
| System Attribute | Value |
|---|---|
| SYSTEM.Name | Example |
| SYSTEM.EndpointPrefix | http://dummy.com/api/{{URL.CompanyId}}/ |
| SYSTEM.TemplateFolderPrefix | /connectors/example/templates/ |
| SYSTEM.TemplateAttributePrefix | EXAMPLE |
| Request Attribute | Value |
| REQUEST.EndpointPath | users/{{URL.User}}/devices/{{URL.DeviceID}} |
| REQUEST.HttpMethod | POST |
| REQUEST.ContentType | text/plain |
| REQUEST.TemplateFile | new-document.txt |
| URL Attribute | Value |
| URL.CompanyId | CompanyValue |
| URL.User | UserValue |
| URL.DeviceID | DeviceValue |
| Template Attribute | Value |
| EXAMPLE.Variable1 | Value1 |
| EXAMPLE.Variable2 | Value2 |
| Response Attribute | Value |
| RESPONSE.ValidationMode | CONTAINS |
| RESPONSE.ValidationValue | success |