Use this information to configure the GenericXchange module used for flexible data exchange either via a secure Remote Function Call (RFC/SNC) connection or by invoking an Open Data Protocol (OData) service on the related SAP System (either SAP Cloud Essentials or SAP S/4HANA on-premises).

The GenericXchange (GX for short) is a powerful module that allows you to exchange any metadata between SAP and Content Services by using a Low Code approach. This means the configuration is done in a JSON file that must be uploaded to Content Services. Once uploaded, the changes are reflected immediately, and no restart of the application server is required. The module can either invoke any OData service in SAP Cloud Essentials as well as in an SAP S/4HANA on-premises system, or it can be used to call any remote enabled function module in an SAP S/4HANA on-premises system using RFC via the SAP JavaConnector.

Basic configuration

Once the module is successfully installed, you’ll need to apply some basic settings in the alfresco-global.properties. These changes require a restart of the application server afterwards.

Settings for OData

If you’re configuring data exchange via OData services, the properties in the table below must be added.

Note: In general, any REST service can be invoked by the Content Connector for SAP Cloud. As the primarily connection is intended to connect to an SAP Cloud system, this documentation uses the word OData from now onwards.

It is possible to have up to 100 different Jobs, where each can invoke a separate OData service. This can be accomplished by duplicating the both properties and increasing the number within the key names.

Settings for RFC/SNC

If you’re configuring data exchange via RFC/SNC by calling an SAP function module with the SAP JavaConnector, the properties in the table must be added.

Note: To invoke function modules with the SAP JavaConnector, the required native libraries from SAP need to be available. These must be downloaded from the SAP Support Portal for the current system architecture.

Note: For both, OData and RFC/SNC, it is possible to have up to 100 separate configurations, where each can invoke a separate configuration file in Content Services. This can be accomplished by duplicating all properties above and increasing the number within the key names.

Prepare Content Services

Once the related settings in the alfresco-global.properties are applied, check if the following folder exists in Content Services: Data Dictionary > SAP Content Connector > genericXchange.

If the folder (structure) doesn’t exist then create it. Pay attention to the correct spelling (i.e. uppercase, lowercase, and spaces).

This is the folder to upload all JSON configuration files that are responsible for data exchange.

Using Jobs or Behaviours

You can schedule the data exchange on a periodic basis (using a Job) or based on a particular action on the document/folder (using a Behaviour) in Content Services. Each method requires a slightly different JSON notation.

Note: The recommendation is to always use a Job whenever possible.

Behaviour approach

Note: Using this approach requires a separate SAP (system) user.

Job approach

Note: You must set exclusion criterion in the mandatory query of the filter property of the JSON. To set a flag after the SAP function module has successfully processed the document, use the success property. The success property can set any property to an arbitrary value at the Alfresco document. Then, use this property value for the exclusion criterion in the query. If there is no exclusion criterion set, the document(s) are repeatedly picked up in the next Job execution.

Mapping

The mapping between the settings part in the alfresco-global.properties (see Basic configuration) and the related JSON file uploaded to Content Services is done via filename of the JSON file, and is different for OData and RFC/SNC usage.

Mapping for OData Services

A JSON file with name restJob.1.json is mapped to keys genericXchange.rest.sap.system.1.job.enabled and genericXchange.rest.sap.system.1.job.cronExpression in the alfresco-global.properties.

Mapping for RFC/SNC invoked by Job

A JSON file with name rfcJob.1.json is mapped to all keys starting with genericXchange.rfc.sap.system.1.* in the alfresco-global.properties. See Settings for RFC/SNC.

Mapping for RFC/SNC invoked by Behaviour

A JSON file with name rfcBehaviour.1.json is mapped to all keys starting with genericXchange.rfc.sap.system.1.* in the alfresco-global.properties. See Settings for RFC/SNC.

In addition, the value of genericXchange.rfc.sap.system.1.name must match the value of key sapName in the related JSON file.

Note: The value for genericXchange.rfc.sap.system.1.name (and therefore even the value for sapName in the JSON) should only consist of characters (a-z, A-Z) and/or numbers (0..9). No whitespace, special characters or any character beyond 128 in the ASCII table.

Configuration

Below are the configuration options for the Job and Behaviour JSON file(s), with a detailed property specification.

Job JSON

The following table lists all available settings for the restJob.1.json (= OData) respective rfcJob.1.json. The column Required For specifies for which type the setting must be present in the JSON configuration file (i.e. either OData, RFC, or All).

Behaviour JSON

Note:

• Make sure you have all the required RFC related settings present in alfresco-global.properties.
• Make sure you always use a separate paid SAP (system) user for the connection.

Important: Each change in the JSON configuration file for a Behaviour requires a reload of the script on all Content Services nodes (or by restarting each Content Services node). To reload the Behaviour JSON file, a Webscript with name genericXchange Reload is provided. This Webscript is part of the Content Connector for SAP - genericXchange Webscript family which is accessible in the Alfresco WebScripts Home.

The following table lists all available settings for the rfcBehaviour.1.json, as it’s not possible to use OData calls along with an Alfresco Behaviour. All the settings below must be present in the JSON configuration file.

Property specification

This section contains the detailed Object definitions for the example values in the tables above.

Property success

Note: This is an optional property.

This property stores the defined text (key state) in any available Alfresco document property (key alfProp) once the SAP function module returns successfully. To handle errors, refer to the property error .

Example

Code copied to clipboard.
"success": {
    "alfProp": "connexasAdministration:sapstatus",
    "state": "Linked to SAP"
}

Property error

Note: This is an optional property.

If the OData call returns with an error, the returned value of this error property can be written to any available property on the current document in Content Services.

Example

Code copied to clipboard.
"error": {
    "alfProp": "connexasAdministration:sapstatus",
    "state": "Error",
    "message": {
        "connexasAdministration:saperror": "error.message.value",
        "cm:description": "error.message.statusCode"
    }
}

Property filter

This property queries all documents in the repository for processing based on the given query. It also specifies the maximum number of tries where the files are picked up for processing until it is excluded (e.g. in case of errors). For RFC/SNC calls (but not for OData), an additional archiveIds parameter is available.

Note: Don’t forget to specify exclusion criteria for the documents in the query.

Example

Code copied to clipboard.
  "filter": {
    "query": "TYPE:\"cm:content\" AND NOT ASPECT:\"cm:titled\"",
    "errorThreshold": 10,
    "archiveIds": [ "D1" ]
  },

Property request

This property defines all required data to call an OData service.

Property for endpoint

This property is a child element of request.

Note: Only OData services that return a JSON response are supported.

Example for property request Return Product Master Records

Code copied to clipboard.
"request": {
    "method": "get",
    "validateCertificate": true,
    "baseUrl": "https://mysapcloud-api.s4hana.ondemand.com/sap/opu/odata/sap/",
    "endpoint": {
        "url": "API_PRODUCT_SRV/A_Product('{1}')?$format=json",
        "substitutions": [
            {
                "alfProp": "sapbo:Product:Product"
        }
        ]
    },
    "headers": {
    },
    "body": {
    },
    "credentials": {
        "user": "USERNAME",
        "password": "PASSWORD"
    }
},

Property response

Note: Only OData services that return a JSON response are supported.

This property defines how the values in the response of the OData call are mapped to the data-model properties of Content Services. The content is a list of key-value pairs. The key defines the name of the data-model property in Content Services where the value should be stored. The value for the key in turn specifies the path to the desired element in the JSON map which holds the value. It can be accessed by using the format $.d.KeyName.

Example

Code copied to clipboard.
"response": {
    "cm:name": "$.d.Product",
    "cm:title": "$.d.Language",
    "cm:description": "$.d.ProductDescription"
},

Property functionModule/functionModules

Note: Only required for RFC/SNC calls. Refer to Job JSON overview table above.

This parameter holds the specification of the function modules which is invoked by the job.

• If the mode parameter is set to chain, this section requires a list of objects, and therefore the parameter name must be set to functionModules (plural). This means the SAP Function Modules in this list are invoked in the given order.
• If the mode parameter is set to standard or custom, the parameter name must be functionModule (singular) only. The table below breaks down the structure required to fill this parameter.

Property importParams

This property is a child element of functionModule / functionModules and is an array which holds a list of objects with all required import parameter of the SAP Function Module that should be used.

Property content

The structure of property content depends on the value set in the property paramType.

Property content when paramType = struct

This property is an array of parameters, where each parameter can be of type struct, parameter or table.

Example

Code copied to clipboard.
{
    "paramType": "struct",
    "name": "DATA_GENERAL_EXP",
    "content": [
        {
            "sapProp": "DESCRIPT",
            "alfProp": "cm:description",
            "type": "string"
        }
    ]
}

Property content when paramType = parameter

This property is an object containing the following keys which pass the desired values from the document in Content Services to the current SAP import parameter.

Example

Code copied to clipboard.
{
    "paramType": "parameter",
    "name": "QUERY_TABLE",
    "content": {
        "alfProp": "cm:created",
        "type": "date",
        "format": "ddmmYY"
    }
}

Property content when paramType = table

This property is a list of SAP table rows which contains a list of SAP table columns. Each cell has the following properties:

Example

Code copied to clipboard.
{
    "paramType": "table",
    "name": "OPTIONS",
    "content": 
    [
        [
            {
                "sapProp": "TEXT",
                "alfProp": "ARC_DOC_ID = '${connexasArchivelink:sapid}'",
                "type": "string"
            }
        ]
    ]
}

Property exportParams

This property is a child element of functionModule / functionModules and is an array which holds a list of objects with all export parameters provided by the SAP Function Module.

Property content when paramType = struct

This property holds an array of parameters. Each parameter can be of type struct, parameter, dynamicExportTable or exportTable.

Example

Code copied to clipboard.
{
    "paramType": "struct",
    "name": "DATA_GENERAL_EXP",
    "content": [
        {
            "sapProp": "DESCRIPT",
            "alfProp": "cm:description",
            "type": "string"
        }
    ]
}

Property content when paramType = parameter

This property is an object containing the following keys which are responsible for storing the return value from the SAP export parameter to the Alfresco document.

Example

Code copied to clipboard.
{
    "paramType": "parameter",
    "name": "QUERY_TABLE",
    "content": {
        "alfProp": "connexasArchivelink:creationdate",
        "type": "datetime",
        "format": "yyyy-MM-dd HH:mm:ss"
    }
}

Property content when paramType = dynamicExportTable

Example

Code copied to clipboard.
{
    "paramType": "dynamicExportTable",
    "name": "DATA",
    "content": [ {
            "alfProp": "cm:name",
            "type": "string"
            "sapPropStart": 123,
            "sapPropEnd": 145,
        }
    ]
}

Property content when paramType = exportTable

This property is an object containing the following keys which are responsible for storing the defined columns of the first row returned from the SAP export table.

Example

Code copied to clipboard.
{
    "paramType": "exportTable",
    "name": "CONNECTIONS",
    "content": [
        {
            "sapProp": "OBJECT_ID",
            "alfProp": "connexasReplicate:sapobjectid",
            "type": "string"
        },
        {
            "sapProp": "AR_OBJECT",
            "alfProp": "connexasReplicate:saparchiveobject",
            "type": "string"
        },
        {
            "sapProp": "AR_DATE",
            "alfProp": "connexasReplicate:archiveDate",
            "type": "date",
            "format": "yyyy-MM-dd"
        }
    ]
}