Zum Hauptinhalt springen

Tasks

Tasks are essentially actions executed against the SAP system, containing either an RFC or a REST service call, along with necessary property mappings. Each action must be defined in a separate file located under the /configs/tasks/ folder of aqishare.

tip

We recommend choosing a file name for tasks that briefly describes the function it performs. This practice improve clarity and organization within the configuration. Examples include barcode.yaml, replicateMetadata.yaml, or startSAPWorkflow.yaml, where each name indicates the task's primary role or operation.
It is also possible to create a subfolder structure under the /config/tasks/ folder and place the files there.

Parameter Overview​

The table highlights all available parameters to specify a task in the corresponding task file.

ParameterMandatoryTypeDefaultDescription
enabledNoBooleantrueIf set to false, the task is disabled and will not processed.
storageYesStringThe value of the name parameter in the related storage.yaml to which the task should connect.
Refer to chapter storage.yaml.
sapYesStringThe value of the name parameter in the related sapConnection.yaml to which the task should connect.
Refer to chapter sapConnection.yaml.
triggerYesObjectDefines the execution of the task, either periodically through a CRON expression or on demand via an access key to manually trigger the task.
Refer below to section Parameter trigger.
queryYesObjectDefines the query which will be executed against the repository (storage) to retrieve data that should be processed.
Refer below to section Parameter query.
mappingYesObjectSpecifies the SAP function module or REST service, and defines the property mapping to be passed to SAP, as well as the property mapping of the result to the repository's properties.
Refer below to section Parameter mapping.
maxRetryNoNumber3The total number of attempts to retry the job before marking it as an error. If this number is exceeded, the document will be excluded from each subsequent run.
priorityNoNumber1Change the priority of this job queue.
retentionNoDuration0Duration for a task to remain in the queue after successful completion, such as 5m or 1h.
timeoutNoDuration3mSpecify a timeout to ensure that if the task isn't processed within that period or before the deadline, the server can abandon the work to reclaim resources for other tasks.

Parameter trigger​

The trigger controls how tasks are initiated. This can be done either automatically via a CRON expression or manually through an access token from third-party systems.

ParameterMandatoryTypeDescription
cronYesStringThe CRON expression used to automatically invoke the task at specified intervals. CRON expressions define a schedule for recurring tasks, allowing for precise control over when the task is executed.
accessTokenNoStringAn arbitrary token is used to allow manual triggering of each task from any third-party system. Ensure that each task has a unique token to avoid conflicts and maintain security. It is advisable to use a randomly generated token with at least 50 characters to minimize the risk of unauthorized access. If this parameter is not set, invoking the task from third-party systems is not possible.

The below example configuration of the trigger parameter illustrates its use with a CRON expression (set to run every full minute) and the option to trigger the task at any time externally using an accessToken.

Example
trigger:
  cron: '* * * * *'
  accessToken: 'eyJhbGciOiJIUzI1NiJ9.eyJSb2xlIjoiQWRtaW4iLCJJc3N1Z'

Manually trigger a Task using an accessToken​

To manually trigger a Task, an accessToken must be specified. The value of this token should be included in the App-Auth header of the request. The endpoint on the aqishare server is /tasks/, followed by the name of the task file, excluding the file extension. Assuming the task is defined in the file /tasks/barcode.yaml and the accessToken is set to the value from the example above, the request should be formatted as follows:

  curl --location --request GET 'http://<aqishare-server>:3000/tasks/barcode' \
      --header 'App-Auth: eyJhbGciOiJIUzI1NiJ9.eyJSb2xlIjoiQWRtaW4iLCJJc3N1Z'
warning

Trigger the action on the SAP side via the accessToken may require a full-paid SAP user (SID) for the connection defined in sapConnection.yaml.

Parameter query​

The query parameter specifies the query sent to the repository to search for related documents. Given that the underlying repositories differ significantly, necessitating distinct handling approaches, the documentation for this parameter is segregated based on the specific repository to enhance clarity.

Parameter mapping​

The mapping parameter specifies the RFC function module or REST service call. It also defines the return mapping, which assigns return values to properties in the repository. Since the specifications for RFC and REST differ significantly, the documentation for this parameter is separated to enhance clarity.

The mapping property defines the assignment of properties between the repository and the desired RFC function module or Rest service, which are required to run the action on SAP side. It also outlines the return mapping, which is the assignment of return values to properties in the repository.

PropertyMandatoryTypeDescription
typeYesStringThe connection type to be used for invoking SAP. Use rfc to call function modules through RFC. For calling a REST (OData) service, use rest.
sapFunctionsYesObjectThe object containing the property assignments. Refer below to Property sapFunctions specification.
successYesObjectHandle the success case of the SAP return. Refer below to Property success specification.
failureYesObjectHandle the error case of the SAP return. Refer below to Property failure specification.

Property sapFunctions​

This property, a subset of the mapping property, includes the assignments of all properties from the repository that must be mapped to the import parameters of the SAP function module. It also manages the return mapping, which involves determining which properties from the result should be mapped to specific properties of the document in the repository.

PropertyMandatoryTypeDescription
- nameYesList/StringThe name of the remote enabled SAP function module that should be invoked. The sapFunction property allows to invoke multiple SAP function modules. By that, the name property defines a list in the YAML syntax and has to be prefixed with a Hyphen.
importParamsYesListList item of name. Handle mapping of all import parameter of the SAP function module.
Refer below to Property importParams specification.
exportParamsYesListList item of name. Handle mapping of all import parameter of the SAP function module.
Refer below to Property exportParams specification.
Property importParams​

This property is a child of the sapFunctions property. It defines the mapping between repository properties and import parameter of the SAP Function Module using a list of Content Properties. In this case, the source is a property from the repository and the target is a name of an import parameter of the SAP function module.

Example​

This excerpt calls the SAP function module ARCHIV_GET_CONNECTIONS and set the import parameter ARCHIV_ID to the value of the property sapHttpContent:archiveId and ARC_DOC_ID to the value of sapHttpContent:docId from the current document.

mapping:
  type: rfc
  sapFunctions:
    - name: ARCHIV_GET_CONNECTIONS
      importParams:
        - target: ARCHIV_ID
          source: sapHttpContent:archiveId
        - target: ARC_DOC_ID
          source: sapHttpContent:docId
Property exportParams​

This property is a child of the sapFunctions property. It defines the mapping between the export parameter of the SAP Function Module and the repository properties using a list of Content Properties. In this case, the source is a name of an export parameter from the SAP function module return and the target is a property in the repository. Properties in the export parameter structure can be addressed by JSON syntax.

!> Address properties in the SAP function module return with JSON syntax.

!> To store properties where the related Facet is not yet on the document, add the Facet name as prefix for the target value.

Example​

This excerpt handle the result of the SAP function module ARCHIV_GET_CONNECTIONS and saves the OBJECT_ID into field sapObjectId and SAP_OBJECT into field sapObject of the current document. As the OBJECT_ID is returned in a table called CONNECTIONS that has only one result line, the source parameter must be set to CONNECTIONS.0.OBJECT_ID.

mapping:
  type: rfc
  sapFunctions:
    - name: ARCHIV_GET_CONNECTIONS
      importParams:
        ...
      exportParams:
        - source: CONNECTIONS.0.OBJECT_ID
          target: 'fct_sap_replicate_details:sapReplicateDetails:sapObjectId'
        - source: CONNECTIONS.0.SAP_OBJECT
          target: 'fct_sap_replicate_details:sapReplicateDetails:sapObject'
Content Property​

Specification of the available content properties used for importParams, exportParams, success and failure.

PropertyMandatoryTypeDescription
sourceYesStringFor exportParams it must be a list property in the YAML syntax (requires a hyphen as prefix). For importParams, depending on the constant or script setting below, the value can either be a hardcoded or parsed/formatted by Javascript.
targetYesStringSame explanation as above - but reversed: For importParams it must be a list property in the YAML syntax (requires a hyphen as prefix) and for exportParams the constant or script has effect.
constantNoBooleanSet true to return a constant value in source (for importParams) or target (for exportParams). Set false to return a value based on the return of the SAP function module. Default: false.
scriptNoStringModify the value using JavaScript functionality before sending or after retrieving it, for instance, by parsing (for exportParams) or formatting (for importParams) the value. Refer to section below.
Using script parameter​

Use the script parameter to modify the value using JavaScript functionality. This is beneficial when the value requires parsing and formatting to meet a specific format. Handling Date objects and Boolean values are examples of situations where this parameter can be effectively utilized.

The following properties will be passed to the script, allowing them to be accessed within it.

PropertyDescription
loggerThe logger instance. Can be used to log various activities within the script.
propsThe properties of the current document being processed by the function module.
dateFnsUse this if the value needs to be formatted as a date or parsed from a date. You can utilize any function from the date-fns library.
contentThe content of the currently processed property in the configuration includes target, content, and, if present, script and constant.
valueThe value from the target parameter when used in the context of importParams, or from the source parameter in the context of exportParams.
  1. Example mapping to send a Date from Nuxeo to SAP.
  • Value for dc:created in Nuxeo: 2022-12-24T11:59:06.375Z
  • Pattern used to parse this as date: yyyy-MM-dd'T'HH:mm:ss.SSSxxx
  • Pattern used to format the parsed date to match the format of the SAP import parameter (type DATS): YYYYMMDD

The corresponding script parameter for the import parameter AR_DATE, used to invoke the function module ARCHIV_CONNECTION_INSERT with the Date from Nuxeo, will look like:

...
  sapFunctions:
    - name: ARCHIV_CONNECTION_INSERT
      importParams:
        - target: AR_DATE
          source: dc:created
          script: dateFns.format(dateFns.parse(value, "yyyy-MM-dd'T'HH:mm:ss.SSSxxx", new Date()), "yyyyMMdd")
          ...
  1. Example mapping to send a Boolean value to SAP.

In SAP ABAP, the concept of a Boolean data type does not exist. Instead, ABAP uses integer types or character types to represent boolean values. Typically, a single character type CHAR(1) is used, with 'X' representing true and a space ' ' representing false.

The corresponding script parameter for the import parameter LATE in structure DOCUMENT_ENTRY, used to invoke the function module ARCHIV_PROCESS_RFCINPUT with the Boolean value from Nuxeo, will look like:

...
  sapFunctions:
    - name: ARCHIV_PROCESS_RFCINPUT
      importParams:
        - target: DOCUMENT_ENTRY.LATE
          source: sapStartWorkflow:sapLateArchiving
          script: 'value === true ? "X" : ""'
          ...

Property success​

This property, a child of the mapping property, is utilized to manage the SAP function module call in successful scenarios. For instance, it can be employed to establish an exclusion criterion that prevents subsequent task runs from reprocessing the same document (as referenced in the Property query above).

Example​

This configuration will add the aqilink "SAP Task Status" facet (fct_sap_task_status) in Nuxeo to the document if it is not already present. It will then set the status property of the facet to the constant value Success and the error property to No Error.

success:
  - source: 'Success'
    constant: true
    target: 'fct_sap_task_status:sapTaskStatus:status'
  - source: 'No Error'
    constant: true
    target: 'fct_sap_task_status:sapTaskStatus:error'

Property failure​

Similar to the success property, the failure property is also a child of the mapping property. However, in contrast, it is used to manage any errors returned by the SAP function module (or REST call).

Example​

This configuration will add the aqilink "SAP Task Status" facet (fct_sap_task_status) in Nuxeo to the document if it is not already present. It will then set the status property of the facet to the constant value Error and the value of the error property to the value of the SAP parameter MESSAGE that is returned as Exception in the Exceptions tab of the SAP function module.

  failure:
    - source: 'Error'
      constant: true
      target: 'fct_sap_task_status:sapTaskStatus:status'
    - source: MESSAGE
      constant: false
      target: 'fct_sap_task_status:sapTaskStatus:error'