1. Using Processes in Oracle Integration Generation 2
  2. Developer Tasks
  3. Integrate Documents
  4. Create a Document- or Folder-Initiated Process

Create a Document- or Folder-Initiated Process

Use the Document Start event to model a process that can be initiated by a document. Use the Folder Start event to model a process that can be initiated by a folder.

You must have an Oracle Content Management, and you must configure a connection between that service and your Oracle Integration before you can create a document-initiated or a folder-initiated process.

By enabling the Oracle Content Management integration, you can define folders that will be created automatically on Oracle Content Management for every process instance, providing a predefined organization of the documents involved. You can also override the access type at the task-level to define the right permissions for that folder or document for a particular task based on your business needs. For example, you might want to prevent users from viewing a classified document or folder associated with a task.

Note these access requirements for a successful integration:

  • The Oracle Content Management user configured in Oracle Integration must have full access to the folder (that is, the folder of the incoming document) configured in Oracle Content Management to be able to kick off a process.

  • For a folder-initiated process (that is, a process with a Folder Start event), the Oracle Content Management user configured inOracle Integration must have manager access to that folder in order to access the folder in Oracle Integration. For example, manager access is required to see the folder on the Task Details page and the Process Tracking page, access the folder when embedding Process UI components in an external application, or see the folder in the Process Mobile application.

  • The Oracle Integration user configured in Oracle Content Management must be granted the process initiator role in order to see the process in the process list for a folder and to be able to initiate the process instance upon arrival of a new document.

To design a process that can be started by a document or folder:

  • Define the Incoming Document or the Incoming Folder in Oracle Integration.

  • Model a process that has a document start event or a folder start event.

  • Customize its implementation to map the start event with the corresponding incoming document or folder you created. Implementation options allow you to define the way in which the document or folder is exposed to users.

  • Modify what role can access the document or folder at the task level (optional).

  • Configure the folder on Oracle Content Management to initiate a process on document arrival.

Alternatively, you can use REST APIs to instantiate a process instance and provide all the input values.

Define the Incoming Document or Folder

To define the incoming document or folder, open the process application you are modeling and click Documents. The Documents page lists the incoming documents and incoming folders that have already been defined.

To create a new incoming document or folder, click New New icon, select the appropriate type, enter a name, and select the default access (permission).

Model Processes with Document or Folder Start Events

Next, build your process that has a document start or folder start event. In the current release, there are some limitations for how you can create the process. Failure to follow the required procedure will invalidate the process.

Caution:

You must add the document start or folder start event from the Elements palette. Only a single, and only the first, start event that you add to a process will be supported. Multiple start events aren’t supported in this release. Also, don’t change a start event using the Change Type option, and don’t delete the first start event. Both actions will invalidate the process for use.

To model a process that has a document start or folder start event:

  1. On the Application Home tab, click Processes.

  2. Click New process New process icon to open the Create Process dialog.

  3. Select None.

    Note:

    Be sure to select None. You will change this empty start event later.

  4. Enter a name for the process, confirm the Open Immediately check box is selected, and then click Create.

    The canvas displays the start and end events in the process.

  5. Click Events in the Elements Palette.

  6. Drag either the Document Start event or the Folder Start event to the canvas.

  7. Add a sequence flow from your new document or folder start event to the end event.

  8. Delete the empty start event.

  9. Continue to modify and define the process. Be sure to test and deploy the process.

Allow All Users to Start a Document- or Folder-Initiated Process

To allow any valid user to upload a document to start a process:

  1. Open the process.

  2. In the swimlane with the document or folder start event, click the role name and then click Edit Edit icon.

  3. In the Role field, select Automatic Handler.

    Description of automatic-handler.png follows
    Description of the illustration automatic-handler.png

Customize Your Document- or Folder-Initiated Process

After you model the process, you can add a start document or folder in a process and customize it.

In your process, click Document Start or Folder Start event in the process diagram. From the icons that display, click Menu Menu icon and then select Open Properties. The Properties pane expands into view below your process diagram.

Define how you want to handle the incoming document or folder:

  • In Place: Selecting this value keeps the location of the document as it is wherever it is. Optionally, you can map the incoming document or folder with one of the predefined documents or folders (open the drop-down list) for its management.

    If there isn’t a predefined incoming document or folder suitable for this particular process, then click New New icon to create one.

  • Unmanaged: The document or folder is ignored by the current process. Oracle Integration won’t show an unmanaged document or folder in runtime. It’s up to the process modeler to handle the incoming document or folder. For example, if you want to move the incoming folder or document to another location, then you can use an XPath expression to get properties, such as Id or Type, and pass the property information to a REST service.

Customize Access at the Task Level

In your process, click a user task in the flow diagram. From the icons that display, click Menu Menu icon and then select Open Properties.

The Properties pane expands into view below your process diagram.

Click Override to customize the current permission of any element defined.

Configure the Folder

To have a process automatically start when a document is uploaded to a folder, you need to configure the folder on Oracle Content Management to initiate a process on document arrival:

  1. Sign in to Oracle Content Management.

  2. Select the folder.

  3. Select Properties from the menu bar.

  4. Enable the Initiate process on document arrival setting.

  5. Select the process from the list.

  6. Click Save.

The folder and its subfolders are now available for use within the Oracle Integration interface. Any change to a file in the folder or any new file uploaded to the folder triggers the process associated with the folder. You can override the inherited process for a subfolder, but you can’t disable the association with a process.

When a file is uploaded from Oracle Content Management into a folder configured for use with Oracle Integration, the file is used for the task associated with that folder. Users in Oracle Integration can take any actions on the files there, such as approvals. When a task step is completed, the file can be moved or managed according to the defined process.

When Oracle Content Management starts a process, the payload sent to launch the process includes this information:

  • Document ID

  • Document name

  • ID of the user who started the process

  • Type

  • Role (indicates the role that should be used to generate subsequent application links)

  • Version

The following example uses only the document ID and document name for display in the form in Oracle Integration. In addition, the document ID is used for making REST API calls to move or copy the file in Oracle Content Management into the task folder. 

{
   "processDefId":"testing~UserFileApproval!1.0~FormApprovalProcess",
   "operation": "startEvent",
   "params": {
        "id": "D2806600E495B744E66BF3981212FF6185DE89BE6812",
        "type": "d",
        "name": "document-name",
        "startedBy": "user-id",
        "role": "role that should be used to generate subsequent applinks",
        "version": "version"
   }
}

Note:

The first operation in the process must be a start event. Otherwise, the process application will return a 500 error to Oracle Content Management.

As a developer, you must be aware of the following requirements for the process you develop:

  • It needs to be a process that uses an Oracle Content Management Start event.

  • When deploying the process, you need to share it with the user specified for enabling the integration so that user has the rights to trigger the process.

  • For the user who uploaded the file to show up as the user who started the task, the process must use the value passed in the startedby field as the display name for the initiator.

  • If you enable the process integration for a folder, you need to share this folder with the Oracle Content Management user that was used to enable the integration in Oracle Integration.

Use REST API Calls to Instantiate a Process

Most times, you will want to use the document start event or the folder start event to model a process that can be initiated by a document or folder. Alternatively, you can use REST APIs to instantiate a process instance and provide all the input values.

Fetching Processes Started by Documents or Folders

To fetch only those processes that can be started by a document, use the doc value in the interfaceFilter filter for the process-definitions API.

GET /ic/api/process/v1/process-definitions?interfaceFilter=doc

To fetch only those processes that can be started by a folder, use the folder value in the interfaceFilter filter for the process-definitions API.

GET /ic/api/process/v1/process-definitions?interfaceFilter=folder

As with any process, Oracle Integration doesn’t validate if a process instance has already been initiated for the same set of input arguments. An end user can instantiate any number of process instances for the given document or folder details.

Any user who has the permission/role to instantiate this process can invoke the above API to query and fetch the list of processes that can be started by a document or folder.

Instantiating a Process Instance

To instantiate a process instance, including a document-initiated or a folder-initiated process, use the standard API:

POST /ic/api/process/v1/processes

You pass several parameters that define the ID, type, and name of the document or folder.

For example:

{ 
   "processDefId":"process-definition-id",
   "operation": "startEvent",
   "params": {
        "id": "document-id|folder-id",
        "type": "d|f",
        "name": "document-name|folder-name",
        "startedBy": "user",
        "role": "contributor"
    }
}

For the type input parameter, you can enter "d" for document or "f" for folder.

Currently, the role input parameter is ignored. All process participants automatically get contributor role access to the document or folder that initiated the process instance.

Like all processes, only users who are members of the start swimlane role can instantiate a process.

Sample Code

You can use the cURL command to invoke the Process REST API. For example: 

curl.sh
host=localhost
port=7001
user="user_name:password"
curl -H "Content-Type:application/json" -u $user -d @input.json http://$host:$port/ic/api/process/v1/processes

Here is sample input.json that adheres to the required interface. Note that for the type parameter, a "d" indicates document and an "f" indicates folder. 

input.json
{ 
   "processDefId":"default~DocumentStart!2.0~Process1",
   "operation": "startEvent",
   "params": {
        "id": "document-id|folder-id",
        "type": "d|f",
        "name": "document-name|folder-name",
        "startedBy": "user",
        "role": "contributor"
    }
}

And here is the sample response returned by this API:

JSON response
{
  "levels": 0,
  "links": [
    {
      "href": "http://abc01abc.example.com:7001/ic/api/process/v1/processes/19",
      "length": 0,
      "rel": "self"
    },
    {
      "href": "http://abc01abc.example.com:7001/ic/api/process/v1/processes/19/audit",
      "length": 0,
      "rel": "audit"
    }
  ],
  "title": "Instance #19 of Process1",
  "processId": "19",
  "processDefId": "default/DocumentStart!2.0/Process1g",
  "processName": "Process1",
  "priority": 0,
  "owner": "DocumentStart.ProcessOwner",
  "creator": "myname",
  "state": "OPEN"
}