What is inside a TWX file and how can I inspect or diff process app exports outside Process Designer?

Question

We keep .twx exports in Git but they are binary blobs to us. What is the structure of a twx, can it be read or compared with scripts, and is editing it a supported practice?

Answer 1

A .twx is a zip file. Inside:

META-INF/package.xml        manifest: project (process app / toolkit), branch, snapshot, dependencies (toolkit snapshot ids), and the list of every object with id, type and version id
objects/<type>.<uuid>.xml   one XML per library artifact: 25.* BPDs (BPMN 2.0 + BAW extensions), 1.* services / human services (flow + scripts inside <script> elements),
                            64.* coach views (layout XML, inline JavaScript in <scriptBlock>, config options), 12.* business objects, 7.* teams, 61.* managed files (metadata),
                            4.* tracking groups, 24.* UCAs, 50.* EPVs, 21.* decisions, 2094.* environment variables …
files/<asset id>/<file>     the binary content of managed files (web assets, jars, zips)
<toolkit>.twx (nested)      dependent toolkits included as nested twx when "include toolkits" was chosen at export

# inspect: counts per type and the snapshot
unzip -l app.twx | head; unzip -p app.twx META-INF/package.xml | grep -o '<snapshot [^>]*name="[^"]*"'
unzip -p app.twx META-INF/package.xml | grep -o 'type="[^"]*"' | sort | uniq -c
# extract the JavaScript of every service and coach view for grep / lint (they are XML-escaped inside the XML)
mkdir x && cd x && unzip -q ../app.twx && python3 - <<'EOF'
import glob, re, html
for f in glob.glob('objects/*.xml'):
    t = open(f, encoding='utf-8').read()
    for i, s in enumerate(re.findall(r'<(?:script|scriptBlock)>(.*?)</(?:script|scriptBlock)>', t, re.S)):
        open(f + f'.{i}.js', 'w').write(html.unescape(s))
EOF
grep -l "console.log\|debugger" objects/*.js                # things that should not ship
# diff two snapshots: normalise the volatile parts (version ids, timestamps) then diff the object XML files by artifact id

Reading and analysing a twx is common practice (static analysers, dependency checks, searching for a hard-coded host across every app); editing a twx by hand and re-importing is possible but unsupported - the import validates ids and the manifest, and mistakes surface as "check the server logs" import failures; if you do it, regenerate version ids, keep the manifest consistent, and treat the result as a new snapshot in a test environment first. For diffs the designer's snapshot comparison (Process Center > snapshot > compare) is the supported view; scripted diffs on the extracted XML are what CI pipelines use for change reports.

References

• BAW documentation - exporting and importing process applications and toolkits