Forms: 3rd-Party Xml Post

Installation Instructions

1. Unzip, upload plugin folder to your plugins directory (/wp-content/plugins/)
2. Make sure Contact Form 7 or Gravity Forms is installed
3. Make sure Forms: 3rdparty Integration is installed
4. Activate plugin
5. Go to new admin subpage “3rdparty Services” under the CF7 “Contact” menu or Gravity Forms “Forms” menu and configure services + field mapping.
6. Configure the new “Xml Post” section to choose which services send as xml and/or determine special headers (given as a url querystring).
7. Nest fields by separating nodes with /, and indicate attributes with @. Numeric indexes by themselves will result in repetition of the parent element (ex. item/%i/sub could make <item><sub /></item><item><sub /></item>).

I need help

Submit an issue to the GitHub issue tracker in addition to / instead of the WP Support Forums.

How do I add / configure a service?

See “base plugin” Forms: 3rdparty Integration.

How do I set headers

Provide the list of headers as though they were a URL querystring, so that

Content-Type: something
X-Special-Header: something-else

would be given as

Content-Type=something&X-Special-Header=something-else

You may also use shortcodes such as base64 in the header.

How do I nest elements?

Separate element names within the same 3rdparty field mapping using /, so that in order to make:

<credentials type="123">
    <user>xyz</user>
    <pass>abc</pass>
</credentials>

you would use credentials/@type, credentials/user and credentials/pass, respectively.

Note: You may nest and wrap elements even if not transforming into XML; they will be submitted as multi-dimensional arrays like:

credentials[@type]=123&credentials[user]=xyz&credentials[pass]=abc

How do I repeat elements?

As of v1.3, if there is a standalone numerical index it will cause repetition of the “parent” element.

ex) If the post is:

item => array (
        0 => value1,
        1 => value2,
        2 => value3
    )

it will result in

<item>value1</item>
<item>value2</item>
<item>value3</item>

You can accomplish this with the Forms-3rdparty separator [%] to place your index appropriately.

How do I set xml prolog attributes?

Just enter the entire root xml in the field, a la http://stackoverflow.com/questions/5992268/simplexml-how-to-correctly-set-encoding-and-xmins

How do I autoclose/not autoclose empty values?

To produce <SomeTag />, make sure the “Autoclose” option is enabled.
To produce <SomeTag></SomeTag>, make sure the “Autoclose” option is unchecked.

How do I completely customize the xml/wrappers/transform?

Use the ‘Mask’ format, which allows you to specify the result exactly as you want via string replacement (sprintf), or the ‘Replace’/’Advanced Replace’ format which will replace string tokens ({{3rdparty}}). Useful for complex XML.

• The ‘Root Element’ field will now be treated as a string-replacement mask (a la sprintf for “Mask” or str_replace for “Replace”), so make sure to include the post body with the appropriate placeholder(s) (%s for “Mask”, {{3rdparty_Fields}} for “Replace”).
• For ‘Mask’ format, each ‘3rd-Party Field’ will also be treated the same, using %s to indicate where the submission value should go.
• For ‘Replace’ format, repeating fields are not handled — it essentially looks for instances of each “3rd-Party Field” column and replaces it with the corresponding input value.
• For ‘Advanced Replace’ format, it works the same except that repeating fields are handled in one of two ways:
  • Providing the shortcode [xpost-loop on="repeatingFieldKey" times="a number"]loop content[/xpost-loop] will repeat the loop content either times or for each key in the array repeatingFieldKey (which is your 3rdparty mapped field)
  • otherwise it will suffix each repeating field key with its index and look for that as a placeholder (e.g. myfield1, myfield2, etc)

How do I use the Advanced Replace format?

For the given mapping:

Source                  3rdparty
------                  --------
input_1                 name
input_2                 phone
input_3.1               files\%i\name
input_3.2               files\%i\name
input_3.3               files\%i\name
input_4.1               files\%i\content
input_4.2               files\%i\content
input_4.3               files\%i\content
input_5.1               files\%i\mime
input_5.2               files\%i\mime
input_5.3               files\%i\mime

Normally the input_3.* fields would get grouped together, as would the input_4.* fields. Using separator [%], it will create a nested list like:

array(
    'files' => array(
        0 => array(
            'name' => 'value of input_3.1',
            'mime' => 'value of input_5.1',
            'content' => 'value of input_4.1' ),
        1 => array(
            'name' => 'value of input_3.2',
            'mime' => 'value of input_5.2',
            'content' => 'value of input_4.2' ),
        2 => array(
            'name' => 'value of input_3.3',
            'mime' => 'value of input_5.2',
            'content' => 'value of input_4.3' ),
))

With Advanced Replacement, you could set the “Root Elements” field to something like the following (which mimics a normal form upload):

--multipartboundaryPE6azq
Content-Disposition: form-data; name="myNameField"

{{name}}
--multipartboundaryPE6azq
Content-Disposition: form-data; name="myPhoneField"

{{phone}}
[xpost-loop on="files"]--multipartboundaryPE6azq
Content-Disposition: form-data; name="myUploadFiles"; filename="{{name}}"
Content-Type: {{mime}}

{{content}}
[/xpost-loop]

Note the use of the shortcode xpost-loop which will repeat for each of the elements in the nested files array, replacing the placeholders accordingly.

1.4.3

• added new “Advanced Replace” format which behaves the same as the existing mustache-style replacement but with xpost-loop shortcode
• fix: cloning row clears textarea field too

1.4.2

• wrapper field is textarea for easier format usage

1.4.1

• fix constructor warning for PHP7

1.4

• new string replacement format using mustache-style token placeholders {{3rdparty}}

1.3.3

• actually fix #24 parsing xml in root

1.3.2

• fix: bug parsing existing xml root
• allow shortcodes in root

1.3

• removed somewhat useless numerical index prefixing (n0, n1, nEtc)
• replaced with element repetition instead

1.2

• ignores xml root when considering escaped backslashes (compatibility break — please update your setting accordingly)
• ‘mask’ format — greater flexibility and control over field/wrapper
• shortcodes in header; base64 shortcode

1.0

• autoclose option
• decided it was good enough to be v1

0.5

• Added multipart/form-data and ‘url’ formatting per GitHub issue #6 https://github.com/zaus/forms-3rdparty-xpost/issues/6
• Added xml prolog/root workaround per GitHub issue #8 https://github.com/zaus/forms-3rdparty-xpost/issues/8
  • Can now enter actual xml as root element for finer customization

0.4.2

Can post body as json instead

0.4

Fixed GitHub issue #3 https://github.com/zaus/forms-3rdparty-xpost/issues/3:

• each plugin setting is only applied to that specific service if it has a value
• removed default post wrapper unless sending as xml (and if you send XML you should specify a wrapper)

0.3

Can nest regular post fields even when not submitting XML.

0.2

• Element nesting, attributes
• reworked “xmlify” using recursive SimpleXMLElement

0.1

Base version – xml and header transformation