Macro tags for Cargo

Special macro that will return a single comma character ','.

Special macro that will return a single percent character '%'.

This macro is available in actions and action sets in the Cargo admin setup. The data that is passed to the action consists of zero, one or more name-value pairs and the key parameter refers to the name of such a pair.

If the action is called from a Cargo form the keys will be the input field ID's.

This is a special macro very rarely used.

In the container of the running application, servlet or applet there are some internal parameters which may be called with this macro. The parameter key differs for each container.

This will take a text and make a base64 encoded text from it. The optional encoding may be used if the source text is in a specific format.

This will take a file and put create a Base64 encoded string from the content. The path argument is the full path to the file to encode.

A macro very rarely used directly in the Cargo environment.

The bucket is a container of name-value pairs. These name-value pairs differs in different macro situations. The key parameter refers to the name in such a name-value pair.

If the value of the key is in a list form the result will be all the lsit values merged with comma and space between them.

This macro is like the BUCKET macro but this will assume that the value is a list of values. The result will be all the individual values merged together with the delimiter between them.

Note! If you want a comma as delimiter, the delimiter value must be %, since comma has a special meaning inside the macro.

This is a special macro with no output. The macro will only modify a bucket value which is a list of values. All duplicate values will be removed from the list value.

This macro is evaluating a condition and will return different values depending on the condition result.

The paramater exp which is evaluated must be a valid expression, see below.

If the expression is evaluated to true, the t text (which may contain other macros) is parsed and returned. If the expression is false the f text is parsed and returned.

The expression exp must contain one (the first occurance is taken) of the following mathematical expression

Will return the character that has the unicode decimal number no.

This will return the unique Cargo Connect ID for the job in the current scope of execution.

This will return the unique file ID for the Cargo Connect production PDF file of the job in the current scope of execution.

This will return the full path to the Cargo Connect production PDF file of the job in the current scope of execution.

Simple form

In the simple form, returns the current date in the format yyyy-MM-dd.

Variant [format]

If format is specified the result will be in the specified format. The format may contain special characters such as dot (.), comma (,) (note! if a comma is to be used as separator it must be escaped with a '%' in order to be handled correctly) and hyphen (-). The characters below shows how to get a certain format. The number of each character decide the result date string, e.g. in the year 2006, yyyy would result in 2006 while yy gives 06.

Variant[+d,format] or [-d,format]

If the first parameter starts with a plus sign or minus sign the specified d number of days will be added or withdrawn respectively from the current date before the result is calculated. The format is as described above.

Note that this macro is only useful in the context where a single file is referred.

File name suffix (dot included) if any. If the file does not have any suffix an empty string is the result.

Note that this macro is only useful in the context where a single file is referred.

Simple form
The file name stem (i.e the file name but without the file name suffix and belonging dot).

Variant [s,e]

Part of the file name stem. Start at index s (the first character has index 1) and end at index e. If s is not specified, 1 is used. If e is missing the last character index is used. Note that the comma characters must be present even if either s or e is left out.

Variant [O,ch]

The first parameter is the letter 'O'. This gives a part of the file name stem starting at the first character and take all characters before the first occurance of ch. If ch is not found in the file name the result is the same as %F%.

Variant [O,ch,no,l]

The first parameter is the letter 'O'. This gives a part of the file name stem starting at the first occurance of ch. Then move no steps (a minus sign may preceed no to go backwards). This is now the start position and l number of characters are read. If l is missing the rest of the file name stem is read. Note that the last comma must be present even if l is left out.

Variant[OI,index,no,l]

The first parameter is the letters 'O' and 'I'. This gives part of the file name stem starting at character index (first character is index 1, if the last character is wanted then use -1). Then no (number) steps will be taken (minus sign may preceed no to go backwards). This is the start and from here l number of characters are read. If l is missing the rest of the file name stem is read. Note that the last comma must be present even if l is left out.

Reading the file with path file (the path is depending on the environment from which this macro is called) and returns the content in the file in the selected text format format.

If the format is omitted, 'UTF-8' is used as default format. Note that the comma must be present even if format is left out.

Optionally the start and end parameters may be used. These will indicate the start and end location to get a portion of the file content. The start and end parameters are the byte location. The first location in the file is zero (0).

This macro is only useful in contexts where a file is present.

This will get the file dimensions in mm. This macro is only available for EPS and PDF files.

The first parameter is the number of decimals to use, if this parameter is missing the default value is set to zero (0) decimals.

The second parameter is only useful when the file is a PDF file. This is then the PDF box to use when getting the dimension. If this is left out the default order will be trimBox,mediaBox,cropBox,bleedBox,artBox.

Also see macro FILE_DIMENSION_W and FILE_DIMENSION_H for more information.

This macro is similar to FILE_DIMENSION but this macro will only get the width part of the dimension.

This macro is similar to FILE_DIMENSION but this macro will only get the height part of the dimension.

Checks if a certain file (with the path path) exists. This will return "true" if the file exists and "false" otherwise.

Gets the file ID of the current file being handled.

Checks if the current file is 'dirty' (i.e. it has been modified but not saved in Cargo Connect production). The result is '1' if the file is dirty and '0' otherwise.

Checks if the current file is is use (i.e. it has been used in a Cargo Connect production document). The result is '1' if the file is used and '0' otherwise.

This macro is only useful in contexts where a file is present.

This will get the value from the file metadata where the key is id.

Note that this macro is only useful in the context where a single file is referred.

The current file's parent folder path.

Note that this macro is only useful in the context where a single file is referred.

The full path to the current file.

Note that this macro is only useful in the context where a single file is referred.

The full path to the current file's preview image file.

Note that this macro is only useful in the context where a cargo file is referred.

This macro will return the file status ID of the cargo file.

Note that this macro is only useful in the context where a cargo file is referred.

This macro will return the file status name of the cargo file.

Note that this macro is only useful in the context where a single file is referred.

The full path to the current file's thumbnail image file.

Note that this macro is only useful in the context where an upload is taking place.

This will give the index of the file beign uploaded.

Returns the number of occasions this file is being used in a Cargo Connection Production document.

This macro may be used inside the macro FOR_EACH_JOB_GROUP_IN_SEARCH. This macro will iterate and evaluate the inner text for each job in the current job group coming from the macro FOR_EACH_JOB_GROUP_IN_SEARCH.

Note that this macro is only useful in a profile action in Cargo where the uploaded files are used.

This is a special iterator macro which will iterate the text (which might contain macros) for each current file. To be able to use any of the file data such as file name in the text the special iterator macros starting with I_ must be used with an iterator index (see %I%).

Only relevant in the context where a job search has been performed, e.g. in an action set where one action has done a search for jobs.

The key is the reference to the job search id (see the settings for a job search action). The iterator text will be iterated for each single job in the rsult from the search.

Only relevant in the context where a job search has been performed, e.g. in an action set where one action has done a search for jobs.

The key is the reference to the job search id (see the settings for a job search action).

The result set will be grouped together based on the grouping key. The grouping key may be any of the following;

Group key	Description
meta-metakey	This will compare the meta data with key metakey. If the value of the meta data is the same these jobs will be grouped together.
jobID	Compares the job ID's and group the jobs with the same ID together.
status	Compares the job statuses and group the jobs with the same status together.
profileID	Compares the job's profile ID's and group the jobs with the same ID together.
lastChanged	Compares the time when the jobs were last changed and group the jobs with the same time together.

When the jobs has been grouped together, each group is iterated and the iterator text is evaluated for each group. Generally the macro FOR_EACH_CURRENT_JOB will be used in the iterator text. For each iterator the bucket will get an extra value with the key bucketID where the value is the value for the group value (e.g. if the grouping was 'status' the value will be the actual status value).

This macro is used to convert a text from one date format to another. For the different pattern characters, see the %D% macro.

The text is the source date specified in the from format. The result is the same date specified in the to format.

Returns a HTML formated text based on the text. Entities such as å will be used instead of å and so on.

Special macro used in the iterator macros starting with I_. The iterator macros need an iterator index and the %I% macro is such an index which automatically will increase for each iteration.

Note that this macro is only useful in a profile action in Cargo where the uploaded files are used.

Special iterator macro used in a iterator macro such as FOR_EACH_FILE.

This macro returns the original file name for the file with index i. See %I% which is commonly used as the iterator index.

Note that this macro is only useful in a profile action in Cargo where the uploaded files are used.

Special iterator macro used in a iterator macro such as FOR_EACH_FILE.

This macro returns the server file name for the file with index i. The server file name is the name the file has on the server which might differ from the original file name. See %I% which is commonly used as the iterator index.

Note that this macro is only useful in a profile action in Cargo where the uploaded files are used.

Special iterator macro used in a iterator macro such as FOR_EACH_FILE.

This macro returns the file download ID for the file with index i. The download ID may be used for example in the email body text of a profile email action where the uploaded file will be available to download directly in the email.

See %I% which is commonly used as the iterator index.

Note that this macro is only useful in a profile action in Cargo where the uploaded files are used.

Special iterator macro used in a iterator macro such as FOR_EACH_FILE.

This macro returns the file ID for the file with index i. See %I% which is commonly used as the iterator index.

Note that this macro is only useful in a profile action in Cargo where the uploaded files are used.

Special iterator macro used in a iterator macro such as FOR_EACH_FILE.

This macro returns the size in bytes for the file with index i. See %I% which is commonly used as the iterator index.

Note that this macro is only useful in a profile action in Cargo where the uploaded files are used.

Special iterator macro used in a iterator macro such as FOR_EACH_FILE.

This macro returns the full path on the server for the file with index i. See %I% which is commonly used as the iterator index.

Note that this macro is only in column value or column mapping in the admin profile setup and admin external database setup.

Variant [type]

This variant of the ICON macro will return one of the built-in icons in the Cargo system. The icons and their type values are seen below;

circleBlack	circleBlue	circleYellow	circleGreen	circleRed	circleGray	circleWhite
checkBlack	checkBlue	checkYellow	checkGreen	checkRed	checkGray	checkWhite
octagonBlack	octagonBlue	octagonYellow	octagonGreen	octagonRed	octagonGray	octagonWhite
squareBlack	squareBlue	squareYellow	squareGreen	squareRed	squareGray	squareWhite
starBlack	starBlue	starYellow	starGreen	starRed	starGray	starWhite
triangleBlack	triangleBlue	triangleYellow	triangleGreen	triangleRed	triangleGray	triangleWhite
xBlack	xBlue	xYellow	xGreen	xRed	xGray	xWhite

Variant [url,url]

This variant has the text 'url' as the first parameter. The second parameter is a full HTTP address from where the image is fetched. Note that the image is not scaled but is shown in 100% size.

Variant [w,h,,type,r,g,b]

This variant will create an icon on the fly with the specified parameters;

w: The width of the icon
h: The height of the icon
type: The type, any of the following values: circle, square, arrowUp, arrowDown, arrowLeft, arrowRight
r, g and b: The color components red, green and blue of the icon.

The text s is searched and the index of the first occurance of t is returned. The index is zero based meaning that if s starts with t the returned index is '0'. If the t is not found in s -1 will be returned.

Both s and t might contain macro text themselves.

If the optional start parameter is present this is the start index in the text from which the search starts. Any occurance of t before this index is not counted. The start index is zero-based meaning that the first character in s has the index 0 (zero).

Note that this macro is only useful where a job is referred.

Simple form

Returns the current job ID. This ID is a unique identifier for each job.

Variant [min]

Returns the current job ID with the minimum length of min. If the ID is not min length the result is preceeded with zeroes (0).
For example: If the ID is "23" and the macro %JOB_ID[4]% is used the result string is "0023".

Gets the curreent job's metadata named key

This macro will return the job status ID of the cargo job.

This macro will return the job status name of the cargo job.

The text s is searched and the index of the last occurance of t is returned. The index is zero based meaning that if s starts with t the returned index is '0'. If the t is not found in s -1 will be returned.

Both s and t might contain macro text themselves.

If the optional start parameter is present this is the index in the text from which the search starts (seen from the end). Any occurance of t after this index is not counted. The start index is zero-based meaning that the first character in s has the index 0 (zero).

Returns the length of the text. The number of characters in text is counted and returned.

This macro may be very useful used for example in an expression, see macro CASE for more information.

The returned value is text where each character is in lower case in the returned value.

This will invoke the mathematical expression math command on the leftExpression and rightExpression. The returned number will have the maximum decimal count that is expressed in the parameter decimals. The leftExpression and rightExpression may contain numbers (possibly from other macros).

The decimals parameter is optional. If decimals is left out the last comma should also be left out.

The math command may be any of the following;

This macro is only useful in contexts where profile data is present, e.g. in profile actions.

This will get a value from the data that a user entered to a profile input form. The data is taken from the profile component with ID id.

Note that in most cases the macros %FILE_META[]% and %JOB_META[]% should be used instead of just %META[]%.

Note that this macro is only useful in the context where a single file is referred.

The macro will return the modification time for the current referenced file. The variants for the macro follow the D macro where more information may be found for the different parameters.

Gets the modification time of a file in milliseconds.

The default version will get the modification time from the current file in scope. The alternative is to pass a file path as parameter which will get the modification time of that file.

The returned value is text where each carriage return is removed. The carriage return is replaced with a space character if there is no space preceeding the carriage return. This means that even if there are multiple carriage returns immediately following eachother in the original text, they will only be replaced by maximum one space character.

This macro is only available in a transfer notification situation set in the external database source. The macro will only return a valid number if the currently selected job in the Dispatch interface is a single PDF file.

The currently selected PDF file's format of the box specified is returned. If the second parameter is the letter 'w' the width is returned, if the second parameter is the letter 'h' the height is returned. The format that is returned is expressed in points. The MATH macro may be used to convert the value to other formats, e.g. mm.

The valid box names are;

Note that this macro is only useful in the context where a file is referred.

This macro is similar to the F macro but the name is taken from the parent folder. All variants of the macro that are applicable to the F macro are also available to this macro.

Note that this macro is only useful where a profile is referred, e..g in a profile action.

Returns the name of the profile.

Returns a modified version of s where all the occurancies of source are replaced with target.

Note, this macro is only useful in the external database source context and may be used in the result column setup and transfer setup.

The value returned is from the selected row in the external database source. The selected row has values which are set in the server data setup in the external database source. Each such server data has an ID specified. The key refers to those server data IDs.

Safe File Name - This will return the text where all occurancies of the following characters are replaced with underscore (_);

Special macro that will replace all characters except the ones in the list below with a underscore (_)

Characters that will remain unchanged are:

. (dot)

- (dash)

_ (underscore)

0-9 (numbers)

a-z (character a to z)

A-Z (character A to Z)

Returns a portion of the soruce string s. The portion is taken from index start (included) and ends at index end (not included). If end is missing the rest of the string is taken from the start. If start is missing the substring will be taken from the start. The index are zero-based meaning that the first character in s is having number 0.

Note that if start and/or end is left out the commas still need to be present.

Returns a modified version of text. The return value is specialized to fit in XML documents where characters are replaced with entities, e.g. 'Ã¥' is replaced with 'å'. Characters with UTF character number more than 128 are replaced with the entity '&#no;' where no represents the UTF value of the character.

The string text may contain macros.

This macro will remove all leading and trailing spaces from the text

The returned value is text where each character is in upper case in the returned value.

This will return the email of the user currently in the scope of execution.

This will return the login name of the user currently in the scope of execution.

This will return the name of the user currently in the scope of execution.

This will return the password of the user currently in the scope of execution.

This macro will return a unique ID. This ID is a so called UUID.

This macro will evaluate a XPath expression (XPath 1.0).

The text is the XML that will be searched.

The xpath expression is the XPath query to execute.

Parameter 3 and all the following are optional. If they exists they should be entered in the following form: prefix=URI where prefix is the namespace prefix and URI is the URI used for that prefix. If the XML document does not use any namespace prefixes these parameters may be omitted.

If the result is not a single value, see macro XPATHLIST.

This macro will evaluate a XPath expression (XPath 1.0) and it will store the result (as a list) in the specified bucket.

The text is the XML that will be searched.

The xpath expression is the XPath query to execute.

The bucket is the key to the current bucket where the result will be stored. The value is stored as a list and special list macros may be sued, for example %BUCKET_LIST[...]%.

Parameter 4 and all the following are optional. If they exists they should be entered in the following form: prefix=URI where prefix is the namespace prefix and URI is the URI used for that prefix. If the XML document does not use any namespace prefixes these parameters may be omitted.