Process definition

Minimal process definition⚓

A document transaction available on a server is the composition of several steps in order to achieve one goal such as document upload, metadata retrieving, document selection, etc. A server is defined by one process element in the manifest.

As explained in the general requirements, a process must be compatible with all the transport or specifically bind one or more compatible processes with the transports attribute.

Warning

The minimal process definition must contains at least one step as showed behind.

Example

1
<cid:process>
2
    <cid:upload url="http://example.com/upload" required="true"/>
3
</cid:process>

Describe a process⚓

A server may describe its processes. There is two ways to do this description.

System oriented : one or more IRI can be defined in the is attribute. These IRI allow a client to automate the process recognition and selection.

User oriented : one or more localized label and doc attributes can be used to describe the process.

Example

A fully described minimal process could be like following.

1
<cid:process is="http://schema.org/SendAction">
2
    <cid:label xml:lang="en">Upload a document onto Example.com server</cid:label>
3
    <cid:doc xml:lang="en">This process allows a client to upload any resource file onto our Example.com server. Once uploaded, the file will be automatically located into the resources folder of your account
4
    </cid:doc>
5
    <cid:upload url="http://example.com/upload" required="true"/>
6
</cid:process>

Metadata⚓

Any metadata used by a step of the process MUST be previously declared. A used metadata is a metadata called by the needMetas, useMetas and returnMetas attributes of the steps.

Minimal metadata declaration⚓

The minimal declaration of a metadata is composed of a single element meta and its name attribute.

Example
1
<cid:meta name="title"/>

The name attribute is required because its content is used by the needMetas, useMetas and returnMetas attributes of the step.

Describe a meta⚓

A meta could be described in a user-oriented way by label and doc elements and in system-oriented way by the is attribute.

Example
1
<cid:meta name="title" is="http://purl.org/dc/elements/1.1/title https://schema.org/title">
2
    <cid:label xml:lang="en">Title of the document</cid:label>
3
    <cid:label xml:lang="fr">Titre du document</cid:label>
4
    <cid:doc xml:lang="en">This meta should contain the title of document and not name of the file</cid:doc>
5
    <cid:doc xml:lang="fr">Cette meta devrait contenir le titre du document et non le nom du fichier</cid:doc>
6
</cid:meta>
Warning

The descriptions elements does not change any client or server implementation requirement.

Restrain the possible values of a meta⚓

A server could restrain the valid values of a meta in the manifest. This restriction is done with value elements containing the proposed values.

Example
1
<cid:meta name="Content-type" is="http://purl.org/dc/elements/1.1/type">
2
    <cid:label xml:lang="en">Available archive formats</cid:label>
3
    <cid:value>application/zip</cid:value>
4
    <cid:value>application/jar</cid:value>
5
    <cid:value>application/x-tar</cid:value>
6
</cid:meta>

Warning

At this stage of the process declaration, client and server does not have any implementation requirements.

Restriction⚓

A restriction is an implicit meta whose value is set by the server. The client should not send the value but must consider the meta and its value as required for the execution of the process.

Minimal restriction declaration⚓

A minimal restriction declaration contains a restriction element, the name attribute and a value attribute.

Example

1
<cid:restriction name="Zip-file-names-encoding" value="UTF-8"/>

Describe a restriction⚓

A restriction could contain the user oriented (localized label and doc elements) or system oriented (IRIs in the is attribute) description.

Steps definition⚓

The steps are the main part of the process. They define how the client and the server should communicate to process the document transaction. One step represents an exchange of information between the client and the server.

Each step could be defined using the same attributes :

  • required : contains a boolean which indicates if the processing of this step is mandatory or not.

    Mandatory attribute

  • url : contain the url of the server where the client must send the request in order to start the processing of this step.

    Mandatory attribute

  • useMetas : contains the names (the names declared in the meta elements) of the optional metadata.

    Optional attribute

  • needMetas : contains the names (the names declared in the meta elements) of the required metadata.

    Optional attribute

  • returnMetas : contains the names (the names declared in the meta elements) of the metadata returned by the server once the step processed.

    Optional attribute

  • is : contains the IRIs that qualifies the step.

    Optional attribute

Exchange step⚓

An exchange step define a regular request from the client to the server. The user is not directly involved in this transaction.

The technical details of the implementation is defined in the transport section.

ExampleDeclaration example⚓
1
<cid:exchange url="http://example.com/checkAuthorization" is="http://schema.org/AuthorizeAction" required="false"/>

Interact step⚓

An interact step define an exchanges between the user and the server, then between the server and the client.

The technical details of the implementation is defined in the transport section.

ExampleDeclaration example⚓
1
<cid:interact url="http://example.com/interact-pre-delivery" needMetas="dc-title" useMetas="dc-creator dc-modified" returnMetas="dc-title dc-creator dc-modified tags" required="true"/>

Upload step⚓

An upload step define an exchanges between the client and the server .

The technical details of the implementation is defined in the transport section.

ExampleDeclaration example⚓
1
<cid:upload url="http://example.com/upload.php" useMetas="File-name" returnMetas="Public-url" required="true"/>

Asynchronous upload⚓

An asynchronous upload is a specific upload declared by the server when the time needed by the processing of the uploaded file does not allow a synchronous response. The server could then define a user-oriented and/or a system oriented wait system.

  • The user-oriented system reuse the interaction mechanism.
  • The system-oriented system reuse the exchange mechanism. The client must execute the wait step until a valid server response.

User and system oriented wait mechanism must declare a url attribute and could declare the needMetas, useMetas and returnMetas step attributes.

ExampleDeclaration example⚓
1
<cid:upload url="http://example.com/upload?step=start" needMetas="dc-title dc-creator dc-modified tags" required="true">
2
    <cid:systemWait url="http://example.com/wait?method=system" returnMetas="Public-url"/>
3
    <cid:userWait url="http://example.com/wait?method=user" returnMetas="Public-url"/>
4
</cid:upload>