Rest-API Interface

Important information

• To use the ProcMan RestAPI for a process, the actions of that process must use the controller hos_ctr_all.php

• The module m_jcl_copy can't be used. The module m_jcl_copy_auto must be used.

• The module m_jcl_commit can't be used. The module m_jcl_commit_api must be used.

• You must create a new specific process if you want to use the RestAPI. It is strictly not recommended to use normal processes by RestAPI. This will cause problems, because e.g. input validation is not available for the RestAPI. This means if you have a process JCL_NEW, you must create an additional process JCL_NEW_RESTAPI!

Not supported modules:

Important: If a process contains one of the following modules, the process activity can not be used by the ProcMan REST-API.

The following modules are currently not supported:

• m_tws_ad_appl_from_task

• m_tws_adhoc_appl_tws_upd

• m_dsn_*

• m_jcl_recovery (security reasons)

Supported modules

See all modules listed in REST-API Modules

Enabling the RestAPI

Configure hwm_universal_interface_config.php

To enable the ProcMan RestAPI, the hwm_universal_interface_config.php must be configured. This file can be found in "/etc/hwm_universal_interface_config.php". Please set the correct values for "url" and "cainfo" your installation.

The documentation can then be opened by https://<procmanurl>:<port>/hwm_rest_api.php

Important: Make sure that the URL is set correctly. Otherwise, the RestAPI interface dialog (hwm_rest_api.php) can send requests to a different installation.

// Example of a configuration for HWM REST API
'rest_api' => array(
    'connection' => array(
        'url' => 'https://<url>:<port>/hwm_rest_api.php',
        'ssl_verifypeer' => true,
        'cainfo' => '<url>',
        'timeout' => 3600,
        'postfields' => array(),
        'httpheader' => array(),
    ),
    'callback' => array(
        'request' => 'rest_api_request',
        'response' => 'rest_api_response',
    ),
),

...

//
// Callbacks for HWM REST API
//

function rest_api_request(&$connection, $inData, &$errMsg)
{
    $connection['postfields'] = $inData;
    return true;
}

function rest_api_response(&$response, &$errMsg)
{
    // For debugging of eventual response errors uncomment the following line:
    // hwm_log(HWM_LOG_INF, $response);
    return true;
}

Check Command in Actions

Also, please ensure that the process you want to use with the RestAPI is using the "hos_ctrl_all.php" command. See the screenshot below. If your process is using "hos_ctrl.php", you can simply use the newer "hos_ctrl_all.php" as this one is downwards compatible.

Usage

tbd.

FAQ

Enhance login token validity

To enhance the lifespan of the login token, edit the file "etc/hwm_rest_api_config.php" and adjust the "token_validity" (default 1 hour) and "max_token_validity" (default 3 hours).

Input data for the REST-API activity must be entered in JSON format in activity_input_data item of the JSON structure.The format of the data must always be like this:

{
    "process": 226,
    "action": "JCL_NEW_CONFIRM_FI",
    "ignore_predprocess_status": false,
    "activity_input_data": {
        "restart_process": true,
        "task": {
            "t0200": {   ...task name used in the process config (wildcards are allowed)
	          ... here the content depends on individual modules ...	
            }
        }
    } 
}

Tasks are scanned from top to bottom and regular expressions and wildcards can be used in task names. The program merges options of all task blocks whose names match the current task name. it is similar to environment options.

If you want to set some value for all tasks then simply put it in a block with an asterisk as a task name.

Optional parameters are in green in the sample code. Currently there is only one optional parameter called restart_process. Normally you should not enter it. But if you do and set its value to true then the process is restarted from whatever state it currently is. The restart deletes all data created by the process from the database and archives. You can use this option for example if you get an error and wish to restart the process from the beginning instead of creating a new one. Please note that as this restart removes all data of the process then it should be used only in the first activity.