Skip to content

Form URL Writer

The Form URL Writer posts a record's fields to a webservice the way a browser posts a form. It has three ways of doing so, chosen by Post Type:

  • Form URL Encoded — the fields go in the body of the request as key1=value1&key2=value2, with a Content-Type of application/x-www-form-urlencoded. Keys and values are URL-encoded.
  • Parameterised URL — the same pairs go on the URL, as ?key1=value1&key2=value2 appended to the target's Insert Url. The writer sends the values as they are, without encoding them.
  • Multipart Form URL Encoded — a multipart/form-data request carrying form fields and one or more files, for a service that accepts uploads. On a WebAPI target this is also how an integration returns a file to its caller.

Whatever the post type, the writer makes one request per record of its top transaction. It does not send fields of child transactions. It writes only to an http(s) Url or back to a WebAPI caller.

Setup

The Setup tab of a Form URL writer: a Target section with WebAPI selected and the line WebAPI - PDFGET - Pdf Get beneath it, then an Options section with Post Type set to Multipart Form URL Encoded, Rewrite Response Transaction disabled at None, and Make File as Attachment ticked

Transform Id

The unique name of the transform.

Target

An IO controller sets where the request goes. The writer offers two:

  • http(s) Url — the full write-side panel: Encoding Method, Webservice Behaviour, Http Headers, Insert Url, Http Operation and the Modify Field, Modify Url and Modify Operation. The writer sets the request body and Content-Type from Post Type.
  • WebAPI — the response to the request the integration is answering. The section shows a single read-only line naming the endpoint.

Options

Post Type

Form URL Encoded, Parameterised URL or Multipart Form URL Encoded, as above. The default is Form URL Encoded.

Choosing Multipart changes the controls beneath it. It sets Rewrite Response Transaction to None and disables it. On a WebAPI target it also ticks Make File as Attachment.

Rewrite Response Transaction

Reads the service's response back onto the record that was posted, so a value the service returns, such as an id it allocated, is available downstream. The list offers four settings; three apply to this writer.

  • None — the writer ignores the response.
  • Sequential Text Data — the response is JSON, and the writer takes values from it by JPath: an Initial Return JPath for the document and a Response JPath per field. This is the setting Rewrite (HTTP) Write Response describes.
  • Binary Data — the writer takes the response as bytes and places it in a Binary field named SYS.RESPONSE on the record, if the transaction has one. Without that field, the writer discards the response. No path controls appear for it.
  • Keyed Text Data — matches the response to the records sent by a key field instead of by their order. This writer's field dialog has no key field, so use the JSON Writer for a keyed rewrite.

The setting is disabled under Multipart, because the writer does not read a multipart response.

Make File as Attachment

Shown only when Post Type is Multipart Form URL Encoded and the Target is WebAPI. When ticked, the writer marks the file the response carries as a download, so a browser saves it instead of showing it. See Multipart Form URL Handling.

Field Mapping

The Form URL writer's Field Mapping tab, with the Output transaction list above a grid of Field Name, Type, Export, Parameter and Response JPath, and an Edit / Select All Fields / Deselect All Fields toolbar

Initial Return JPath

The JPath into the response document that each field's Response JPath is relative to. Shown above the grid only when Rewrite Response Transaction is Sequential Text Data.

Output

The transaction type being edited.

Field Name

The field name within IMan.

Type

The field's data type within IMan. Read-only here. You set it where the field is created.

Export

When ticked, the writer includes the field in the request.

Parameter

The name the field is sent under (the key in key=value) on the form, the URL or the multipart section.

Response JPath

Where in the service's response the writer takes the value from, relative to the Initial Return JPath. Shown and kept only when Rewrite Response Transaction is Sequential Text Data.

Transaction Type Return JPath

Where in the service's response the selected transaction's records are, relative to the Initial Return JPath. The writer matches the elements it finds there to the transaction's records in order. It sits beneath the grid, and shows under the same setting as Response JPath.

Parameter Type

Used only when the Post Type is Multipart Form URL Encoded. It says which part of the multipart request the field contributes to: Field/Parameter Field, File Type, Content Disposition Name Field or Boundary Field. See Multipart Form URL Handling.

Editing the grid

Edit puts the grid into edit mode and is replaced by Save and Cancel. Select All Fields and Deselect All Fields set or clear the Export tick on every row at once. In edit mode each row gains a drag handle at its left edge, and you can drag rows to reorder them. Order matters for a multipart request, because the order of the fields groups them into sections.

Audit

The writer runs under the same Action on Transform Error as every writer.