Summary

This article covers exporting constant and record based data, input for instructions, chaining instructions, and qualifying strings when creating a custom export.

Table of Contents

• Concepts Covered
• Exporting constant and record based data
  • Constant Domains
  • Record-based Domains
• Input for Instructions
• Chaining Instructions
• Qualifying strings

A custom export allows customizing the export data to special needs. With the “Form Type Id” column the table is specified that should be generated. For each form of the form type a row in the table is created. A cell within such a row is generated with an instruction.

The instructions described on this page are available for export formatters that are derived from class com.clickfind.dataCollector.export.instructions.ExtendableExportFormatter. This custom formatter type can be entered into the dataArchitect file simply as extendable. Your project manager will be able to tell whether your export formatter is derived from that class.

Concepts Covered

This tutorial covers the following topics:

• Exporting constant and record based data
• Input for Instructions
• Chaining Instructions
• Qualifying Strings

Exporting constant and record based data

Usually the export formatters work in the context of a form. There are situations, when it makes sense to export data independent of a record or form and export data in the context of a record only. The extendable export formatter as described in the introduction can handle these situations.

Constant Domains

For CDISC SDTM exports the specification of design data for the study is required. Exporting this with the form based approach is not appropriate as this data will be constant and independent of any clinically collected data and it should exist only once in the final archive. With the extendable export formatter you can design the export domain as you do for any form, but – of course – you cannot use any form or record related information. There is one additional configuration required for constant domains: Enumerate them with the formatter parameter list “constantExportType”, which requires a numeric suffix without any gap. Example:

Record-based Domains

Sometimes it is easier to specify export data in the context of a record than it is for a form, especially when a form type is contained in many visits. With the extendable export formatter you can design the export domain as you do for any form, but – of course – you need to use absolute path expressions, whenever you access a question and you cannot access a form directly. There is one additional configuration required for record-based domains: Enumerate them with the formatter parameter list “recordExportType”, which requires a numeric suffix without any gap. Example:

Input for Instructions

Instructions are used to calculate the content of an export cell. An instruction has access to following information:

• The form for which the current database row is generated. With the form, the record, data collector tool, the application and the properties are available.
• A configuration value for the “Question Id”. In general this configuration needs to be the path to a question either relative from the form or absolute from the record. The value for the question Id might be empty depending on the instruction. It is possible to reference a question ID be name with the prefix “&&”.
• A configured “Value” for the instruction. The value can be any string value that makes sense to the instruction.
• The input value from the previous instruction, see chained instructions.

Please check the documentation for each instruction for details on the behavior and required configuration values.

Chaining Instructions

An instruction performs a special calculation, but it might not exactly do what you need. For this reason it is possible to chain instructions, which allows for more flexibility. Chaining means that each instruction gets an input value, which is the result of the previously calculated instruction.
Example: You need to uppercase value of the first 4 characters of a special question. In this case a first instruction might extract a substring from the desired question’s value. Then a second instruction can take this input and convert the value to upper case. Such an upper case instruction can be useful in multiple situations.
Chaining is configured with the help of a chaining separator, which is $>. This separator is used to separate the instructions, the question Ids, and the value configurations. Here is an example:

It is a good practice to always use the same number of chaining separators in the instructions cell, the question Id cell, and the value cell. Example: When you do not put a chaining separator into the question Id field like this:

In such a case, the question Id value is passed to both the “substring” instruction and the “uppercase” instruction. Most instructions (possibly not all) will use a specified questions Id with a higher preference than an input value from the previous instruction. In this case the uppercase command would use the complete value of the question and not the input value of the leading four characters. Thus forgetting the chaining separator here is a classical bug with undesired behavior.

Qualifying strings

String constants are trimmed before they are processed. This allows for a nice configuration of chained instructions.

Example: If you have a configured value “ABC $> DEF”, then the first chained value is “ABC” and the second one is “DEF”.

If you require to have white-space characters at the front or the end of the string, then you need to qualify the value with either a single quote or a double quote character. The qualifying character needs to be put in front of and behind the text. When the text should contain the qualifying character too, then it needs to be doubled.

Example: ABC can be qualified either as “ABC “ or as ‘ABC ‘. The text He said: “Hello” can be qualified as either ” He said: “”Hello”” “ or ‘ He said: “Hello” ‘.

Which qualifying character should you use? Be aware that Excel might interpret a single quote character as a hint that text follows. This can result in Excel removing the single quote character and preventing the character from making it to the eClinical application. This might result in the recommendation to use the double quote character. However, if your text includes many double-quote characters and you are aware of the Excel behavior, the use of a single quote might be preferred as you do not need to escape the qualifier itself.

Need more help?

Please visit the Fountayn Contact Information page.