Create Macro

Last updated
Save as PDF

createMacro

The createMacro web service is used to create a macro template on QTRACS/Portal. A macro template is a preformatted dynamic message with controlled content in QTRACS/Portal.
For more information about the use of macro templates in Text and Macro Messaging see the Text and Macro Messaging Concepts page.

Customers can optionally use the Portal Event Subscription Service (ESS) to subscribe to Macro Template Definition Acknowledgement notification events and automatically receive acknowledgement transactions in their integration when any macro template modifications have been confirmed (or rejected) by the Omnitracs Network Operations Center.

void createMacro(MacroDefinition macro) throws WSException

macro: A MacroDefinition object that defines the macro template.

Macro Definition parameters

Field Name	Required?	Macro Direction	Comments
assocRtnMac	False	Forward Only	valid values: 1-63
definitionStatus	False	N/A	ignored by this web service
description	True	All
direction	True	All	valid values: "F" - forward macro, "R" - return macro
macroItemList	True	All	must contain 1 - 100 Macro Items to be valid see MacroItem parameters section below for more details
msgSupr	False	All
name	True	All	macro names do not need to be unique as uniqueness is based on number and version
number	True	All	valid values: 1-63
routeCoverage	False	Return Only	specify "true" if the macro should be routed to a vehicle's coverage
rtnMacCoverage	False	Return Only	specify "" (blank) if only vehicle coverage is intended to be used
usage	False	N/A	ignored by this webservice
version	False	N/A	ignored by this webservice (this value is assigned automatically by the NMC)

Macro Item parameters

Field Name	Required?	Comments
column	True	valid values: 1-38
dictName	Conditional	if no dictionary tag is specified, this dictionary name is used to determine the dictionary entry
dictTag	Conditional	dictionary (xml integration) tag; this field takes precedence over dictName when determining the dictionary entry
groupName	False	if no group tag is specified, used to determine the dictionary group - if neither groupName nor groupTag is specified the entry is not part of a field group
groupNum	False	the sequential number of the group within the macro. For example, if there are 3 groups in the macro, the first sequential group is groupNum 1 and the last group is groupNum 3. Dictionary entries within a single group must occur in succession (only labels are allowed in between)
groupTag	False	dictionary (xml integration) tag; this field takes precedence over groupName when determining the dictionary group
length	Conditional	required to specify the length of variable dictionary fields, otherwise ignored
required	False	set to "true" if the field is required to be completed before sending
row	True	valid values: 1-50
type	False	use the string "label" to specify a label, otherwise the entry is assumed to be a dictionary field
value	Conditional	required to specify the value of a label, otherwise ignored

Additional information regarding the use of dictionary entries in the macro template

When creating a macro with this web service, dictionary fields (Macro Item objects) within the macro body must already exist in one of the two QTRACS/Portal field dictionaries: the Standard Dictionary or the Custom Dictionary.
The Standard Dictionary is provided by Omnitracs and contains common field definitions that are preinstalled for all companies.
Each company may also have a Custom Dictionary which contains additional field definitions that cater to the specific needs of the company.

NOTE: dictionary fields within a macro are padded in front and back with a space unless they begin or end a row. Contiguous dictionary fields are only separated by a single space. Therefore, when specifying the starting position of the dictionary field, or the field following, this needs to be taken into consideration.

It is easiest to understand the layout of the row/columns in the createMacro web service using an example. This example will create the macro below (as shown on the QTRACS/Portal UI).

When depicted in tabular form, the required MacroItem entries become clear.

Authorization Requirements

The credentials supplied with this method call (as specified in the accompanying WS-Security header) must be authorized to the following application(s) and their associated role-based permissions.

Required Application Licenses
- Remote Integration

Required User Permissions
- Can use QTRACS
- Can set up macros

Customer integrators are authorized to their own company's data only.

Sample XML Request

Only the SOAP body is shown. To see a sample SOAP Envelope and Header, see the Web Service Security page.

<soap:Body>

<createMacro xmlns="http://websvcs.qtracswebws">

<macro xmlns="">

<assocRtnMac>12</assocRtnMac>

<definitionStatus xsi:nil="true"/>

<description>Shipping Info</description>

<direction>F</direction>

<macroItemList>

<MacroItem>

<column>5</column>

<dictName />

<dictTag />

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>1</row>

<type>label</type>

<value>**** NEXT LOAD INFORMATION ****</value>

</MacroItem>

<MacroItem>

<column>1</column>

<dictName />

<dictTag />

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>2</row>

<type>label</type>

<value>LOAD#</value>

</MacroItem>

<MacroItem>

<column>7</column>

<dictName />

<dictTag>loadNumber</dictTag>

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>true</required>

<row>2</row>

<type />

<value />

</MacroItem>

<MacroItem>

<column>20</column>

<dictName />

<dictTag />

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>2</row>

<type>label</type>

<value>ADD STOPS</value>

</MacroItem>

<MacroItem>

<column>30</column>

<dictName />

<dictTag>addStops</dictTag>

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>2</row>

<type />

<value />

</MacroItem>

<MacroItem>

<column>1</column>

<dictName />

<dictTag />

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>3</row>

<type>label</type>

<value>SHIPPER</value>

</MacroItem>

<MacroItem>

<column>9</column>

<dictName />

<dictTag>shipper</dictTag>

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>true</required>

<row>3</row>

<type />

<value />

</MacroItem>

<MacroItem>

<column>1</column>

<dictName />

<dictTag />

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>4</row>

<type>label</type>

<value>CITY</value>

</MacroItem>

<MacroItem>

<column>9</column>

<dictName />

<dictTag>city</dictTag>

<groupName />

<groupNum>1</groupNum>

<groupTag>cityState</groupTag>

<length>0</length>

<required>false</required>

<row>4</row>

<type />

<value />

</MacroItem>

<MacroItem>

<column>34</column>

<dictName />

<dictTag />

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>4</row>

<type>label</type>

<value>ST</value>

</MacroItem>

<MacroItem>

<column>37</column>

<dictName />

<dictTag>state</dictTag>

<groupName />

<groupNum>1</groupNum>

<groupTag>cityState</groupTag>

<length>0</length>

<required>false</required>

<row>4</row>

<type />

<value />

</MacroItem>

<MacroItem>

<column>1</column>

<dictName />

<dictTag />

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>5</row>

<type>label</type>

<value>P/U FROM</value>

</MacroItem>

<MacroItem>

<column>10</column>

<dictName />

<dictTag>date</dictTag>

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>5</row>

<type />

<value />

</MacroItem>

<MacroItem>

<column>16</column>

<dictName />

<dictTag>time</dictTag>

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>5</row>

<type />

<value />

</MacroItem>

<MacroItem>

<column>25</column>

<dictName />

<dictTag />

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>5</row>

<type>label</type>

<value>TO</value>

</MacroItem>

<MacroItem>

<column>28</column>

<dictName />

<dictTag>date</dictTag>

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>5</row>

<type />

<value />

</MacroItem>

<MacroItem>

<column>34</column>

<dictName />

<dictTag>time</dictTag>

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>5</row>

<type />

<value />

</MacroItem>

<MacroItem>

<column>1</column>

<dictName />

<dictTag />

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>6</row>

<type>label</type>

<value>PRODUCT</value>

</MacroItem>

<MacroItem>

<column>9</column>

<dictName />

<dictTag>variableChar</dictTag>

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>30</length>

<required>false</required>

<row>6</row>

<type />

<value />

</MacroItem>

<MacroItem>

<column>1</column>

<dictName />

<dictTag />

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>7</row>

<type>label</type>

<value>CONSIGNEE</value>

</MacroItem>

<MacroItem>

<column>11</column>

<dictName />

<dictTag>consignee</dictTag>

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>true</required>

<row>7</row>

<type />

<value />

</MacroItem>

<MacroItem>

<column>1</column>

<dictName />

<dictTag />

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>8</row>

<type>label</type>

<value>CITY</value>

</MacroItem>

<MacroItem>

<column>9</column>

<dictName />

<dictTag>city</dictTag>

<groupName />

<groupNum>2</groupNum>

<groupTag>cityState</groupTag>

<length>0</length>

<required>false</required>

<row>8</row>

<type />

<value />

</MacroItem>

<MacroItem>

<column>34</column>

<dictName />

<dictTag />

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>8</row>

<type>label</type>

<value>ST</value>

</MacroItem>

<MacroItem>

<column>37</column>

<dictName />

<dictTag>state</dictTag>

<groupName />

<groupNum>2</groupNum>

<groupTag>cityState</groupTag>

<length>0</length>

<required>false</required>

<row>8</row>

<type />

<value />

</MacroItem>

<MacroItem>

<column>1</column>

<dictName />

<dictTag />

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>9</row>

<type>label</type>

<value>DLVR FROM</value>

</MacroItem>

<MacroItem>

<column>11</column>

<dictName />

<dictTag>date</dictTag>

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>9</row>

<type />

<value />

</MacroItem>

<MacroItem>

<column>17</column>

<dictName />

<dictTag>time</dictTag>

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>9</row>

<type />

<value />

</MacroItem>

<MacroItem>

<column>25</column>

<dictName />

<dictTag />

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>9</row>

<type>label</type>

<value>TO</value>

</MacroItem>

<MacroItem>

<column>28</column>

<dictName />

<dictTag>date</dictTag>

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>9</row>

<type />

<value />

</MacroItem>

<MacroItem>

<column>34</column>

<dictName />

<dictTag>time</dictTag>

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>9</row>

<type />

<value />

</MacroItem>

<MacroItem>

<column>1</column>

<dictName />

<dictTag />

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>10</row>

<type>label</type>

<value>MILES: LOADED</value>

</MacroItem>

<MacroItem>

<column>15</column>

<dictName />

<dictTag>mileage</dictTag>

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>10</row>

<type />

<value />

</MacroItem>

<MacroItem>

<column>21</column>

<dictName />

<dictTag />

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>10</row>

<type>label</type>

<value>EMPTY</value>

</MacroItem>

<MacroItem>

<column>27</column>

<dictName />

<dictTag>mileage</dictTag>

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>10</row>

<type />

<value />

</MacroItem>

<MacroItem>

<column>1</column>

<dictName />

<dictTag />

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>11</row>

<type>label</type>

<value>VOLUME:</value>

</MacroItem>

<MacroItem>

<column>9</column>

<dictName>VolumeItemList</dictName>

<dictTag />

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>11</row>

<type />

<value />

</MacroItem>

<MacroItem>

<column>7</column>

<dictName />

<dictTag />

<groupName />

<groupNum>0</groupNum>

<groupTag />

<length>0</length>

<required>false</required>

<row>12</row>

<type>label</type>

<value>*** END OF MACRO ***</value>

</MacroItem>

</macroItemList>

<msgSupr>false</msgSupr>

<name>ShipInfo</name>

<number>23</number>

<routeCoverage>false</routeCoverage>

<rtnMacCoverage> </rtnMacCoverage>

<usage>0</usage>

<version>0</version>

</macro>

</createMacro>

</soap:Body>

Sample XML Response

An empty response conveys success. If there was an error, an exception would have been thrown.

<soapenv:Body>

<createMacroResponse/>

</soapenv:Body>

Exceptions

002 Null value in one of the SQL null indicator fields.
003 Authenticated company not specified.
004 Authenticated user not specified.
005 User is not authorized.
006 Invalid macro direction specified.
007 Can not create a macro that already exists.
008 Invalid macro number specified.
009 Invalid macro name specified.
010 Invalid associated return macro specified.
011 Invalid return macro coverage specified.
012 Routing coverage must be specified for return macros.
013 Macro template cannot be blank.
014 Error writing new macro record.
015 Dictionary name or XML tag must be specified for a macro field.
016 Invalid dictionary sequence specified.
017 Invalid dictionary/group name.
018 Invalid dictionary/group XML tag.
019 Group name/tag specified for dictionary name/tag or vice-versa.
020 Invalid dictionary length specified.
021 Error writing dictionary mapping record.
022 Dictionary/group name not found.
023 Dictionary/group XML tag not found.
024 Group index not valid.
025 Macro field row or column cannot be zero.
026 Macro template contains one or more overlapping fields.
027 One or more fields exceeds the maximum field length.
028 One or more rows exceeds the maximum row length.
029 Maximum number of allowable dictionary fields exceeded.
031 Invalid macro description specified.
032 A dictionary field with enumerations caused a line wrap resulting in overlapping rows.
033 Maximum number of allowable rows/characters exceeded.
034 One or more labels contain invalid characters.
035 Return macros cannot contain a password field.
036 Macros cannot contain more than one password field.
037 Maximum number of allowable field groupings exceeded. Maximum 100.
038 Macro cannot be modified once text messages are used for OT1.