REST headers

REST requests sent to the Integration Service must include the following elements in the header:

• Accept

• Ima-Group

In a multipart request beside the content type also the type must be specified, for example:

Impersonation

The REST interface supports user and group impersonation based on the headers:

• Ima-Impersonation-User

• Ima-Impersonation-Group

In this scenario an authenticated user acts in the name of another user, the “impersonated user”. Authentication is handled in the same manner like it is done without impersonation, i.e. either with SSL Authentication or Basic Authentication. The user who wants to impersonate another user or group requires the specific permission to do so.

If the header “Ima-Impersonation-User” is present, authorization is done with this user, which means:

• An authenticated agent (user or system user) can act with the rights which this agent and the impersonated user have in common (mathematical intersection of rights).

• If either one of the actors (agent or impersonated user) does not have any rights, impersonation won’t grant any rights, either.

• The rights of the authenticated agent are not extended by the rights of the impersonated user.
  

• And vice versa:

  The rights of the impersonation user during impersonation are not extended by the rights of the authenticated agent.

• The impersonated username is used as entry for the system attributes of a revision in “created by” or “updated by”. It would also be used in such log or audit trail entries that are explicitly set up to contain the username.

If the header “Ima-Impersonation-Group” is present (which can also be used without “Ima-Impersonation-User”), the roles of this group are also used for the combination of roles (as further constituent of a mathematical intersection).

Stamping Service header (REST)

The ImageMaster Stamping Service can be used to retrieve a modified document rendition where a watermark is visible as an overlay. To obtain a stamped rendition, the stamping header can be used:

• ima-stamping-customStamp

The following MIME types are supported by the Stamping Service. Note that text files will be changed to PDF to enable an overlay:

MIME type	File extensions
application/pdf	pdf
text/plain	txt (retrieved document will be a PDF)
image/tiff image/tif	tiff/tif
image/jpg image/jpeg image/jpe	jpeg/jpg
Table 343: Stamping Service MIME types and file extensions

Depending on the existence or the value of this header, the following behavior is achieved:

• Header is not present or has “null” as value:

  • Find all stamps (which have externalStampSelection=false) corresponding to the condition. If there are non-default stamps in the list, the first one applies, otherwise the default stamp applies (stamp with attribute default=true).

• Header has “EMPTY” as value:

  • If the “EMPTY” header is allowed for the document type, no stamp is placed.

    “Allowed” in this context means that a stamp with name “EMPTY” is configured for the document type and the stamp has the attribute externalStampSelection=true.

  • If the “EMPTY” header is not allowed for the document type, an error is returned.

• Header has a stamp name as value:

  • If a stamp with this name is configured and allowed as external stamp (externalStampSelection=true) for the document type, the stamp with the respective name is placed.

  • If a stamp with this name is configured for the document type but is not allowed as external stamp (externalStampSelection=false), an error is returned.

  • If no stamp with this name is configured for the document type, an error is returned.

In the following code block there is an example how to retrieve a document via the REST service. The content of the document will be stamped with the stamp of the name “MyStamp”: