Skip to content

Quickstart: create a template

This example saves a template that opens a URL passed at run time and returns the final address, including any redirect. Run the snippets in order in one Bash session on macOS or Linux; on Windows, use WSL. You need MoreLogin desktop client V2.73.0 or later, curl 7.76 or later, jq, and uuidgen. Keep the generated files: the run example and request recovery use them.

1. Discover capabilities and contracts

Set the port to the Local API port shown in the MoreLogin client. The commands work in a private temporary directory, because real template and run responses can contain sensitive values.

umask 077
RPA_BASE_URL='http://127.0.0.1:40000/api/rpa/browser/v1'
RPA_DIR="$(mktemp -d)" && cd "$RPA_DIR"
rpa_curl() {
  curl --fail-with-body -sS --max-time 30 "$@"
}

If you enabled Local API authentication, add the Authorization header described in Authentication to the curl command in rpa_curl.

Check that the client supports the operations this example uses, and record the catalog revision. Write requests send it back in the X-RPA-Catalog-Revision header.

rpa_curl "$RPA_BASE_URL/capabilities" -o capabilities.json &&
jq '.data | {operations, limits, docs}' capabilities.json &&
jq -e '.data.operations as $ops | ["listNodeTypes","getNodeType","validateWorkflow","createTemplate"] - $ops | length == 0' capabilities.json &&
RPA_CATALOG_REVISION="$(jq -er '.data.catalogRevision' capabilities.json)"

Read the contracts of the four node types in the example. The last command succeeds only if every contract is authorable, supported at run time, runnable through the API, and fully documented. Shared fields and workflow structure explains each contract field.

rpa_curl --get "$RPA_BASE_URL/node-types" --data-urlencode 'q=gotoUrl' -o node-types.json &&
rpa_curl "$RPA_BASE_URL/node-types/start" -o start.contract.json &&
rpa_curl "$RPA_BASE_URL/node-types/end" -o end.contract.json &&
rpa_curl "$RPA_BASE_URL/node-types/browser_gotoUrl" -o browser_gotoUrl.contract.json &&
rpa_curl "$RPA_BASE_URL/node-types/browser_getUrl" -o browser_getUrl.contract.json &&
jq -s -e 'all(.[]; .data | .authorable and .runtimeSupported and .externalRunnable and .documentationComplete)' *.contract.json

AI agents can start from the local guides: rpa_curl "$RPA_BASE_URL/llms.txt" lists the Skill (/docs/SKILL.md) and the API guide. Paths that start with / resolve against http://127.0.0.1:<port>.

2. Validate the full candidate

Save the following body as create.json. Give each node a title that describes what it does. The end node returns its message as the run's outputs.result; here the message is the data.value output of the url_result node.

{
  "title": "Return the final page URL",
  "description": "Visit the supplied page and return its final URL",
  "workflow": {
    "editorVersion": 2,
    "editorParametersVersion": 1,
    "variables": {
      "type": "object",
      "properties": {
        "targetUrl": {
          "type": "string",
          "description": "Absolute HTTP(S) URL to open"
        }
      },
      "required": [
        "targetUrl"
      ]
    },
    "nodes": [
      {
        "id": "start",
        "type": "start",
        "data": {
          "title": "Read the target URL parameter"
        }
      },
      {
        "id": "visit",
        "type": "browser_gotoUrl",
        "data": {
          "browserAction": "gotoUrl",
          "browserUi": {
            "inputs": {
              "url": "${targetUrl}",
              "postWaitMs": 0
            },
            "exception": {
              "timeout": 30000,
              "policy": "interrupt"
            }
          },
          "title": "Open the supplied page"
        }
      },
      {
        "id": "url_result",
        "type": "browser_getUrl",
        "data": {
          "browserAction": "getUrl",
          "browserUi": {
            "inputs": {
              "type": "href"
            },
            "exception": {
              "timeout": 30000,
              "policy": "interrupt"
            }
          },
          "title": "Read the final URL after navigation"
        }
      },
      {
        "id": "end",
        "type": "end",
        "data": {
          "inputsValues": {
            "status": {
              "type": "constant",
              "content": "success"
            },
            "message": {
              "type": "ref",
              "content": [
                "url_result",
                "data",
                "value"
              ]
            }
          },
          "title": "Report the final page URL"
        }
      }
    ]
  },
  "dependencies": []
}
jq '{purpose:"save",source:{kind:"inline",template:.}}' create.json > validate-save.json &&
rpa_curl "$RPA_BASE_URL/validations" -H 'Content-Type: application/json' \
  --data-binary @validate-save.json -o validation-save.json &&
jq '.data | {valid,issues,truncated,runtimeChecks}' validation-save.json &&
jq -e '.data.valid == true and .data.truncated == false' validation-save.json

Read the validation report, including warnings and runtime checks. Continue only when valid is true and the report isn't truncated. Validation doesn't open a browser.

3. Save the template and record the version

([ -s create.key ] || uuidgen > create.key) &&
rpa_curl "$RPA_BASE_URL/templates" -H 'Content-Type: application/json' \
  -H "X-RPA-Catalog-Revision: $RPA_CATALOG_REVISION" \
  -H "Idempotency-Key: $(cat create.key)" \
  --data-binary @create.json -D created.headers -o created.json &&
head -n 1 created.headers &&
jq '.data | {id,version,revisionId,warnings}' created.json

HTTP 201 means the template was saved. Keep the normalized response, which includes the workflow, ID, version, and revision ID, and the ETag in created.headers. The key in create.key identifies this write intent: reuse it only to retry the same request, and generate a new key for a new write. If the request times out, follow request recovery before you send another write.

After the template list refreshes, the template also appears under Custom Templates in the desktop client. To change it later, read its latest version, validate the complete candidate with source.base, and submit the edit with its current If-Match. See Edit an existing template.

Next: run the saved template with the API.