Publishing to CommCare HQ

Publishing sends your app to a CommCare HQ project space. Nova remembers where it went, so you can come back at any time and see how far along it is.

Getting an app into workers' hands takes six stages. Nova completes the first three, you make and release a version on CommCare HQ, and Nova confirms the released app is ready for workers.

The six stages

Nova shows all of these in App setup → Publishing, one card per project space this app has reached, filled in as far as you have got. A version you made on CommCare HQ last week is one Check status away there, and you never have to publish again just to find out where things stand. The card also holds everything else a publish leaves behind: the workers list, the set-up-by-hand notes, and, when you can edit the app and your connected API key reaches that project space, a Publish again that opens the Publish dialog already pointed at it.

The Publish dialog is where a publish starts. With a CommCare HQ connection set up, opening it also shows the same project spaces as short status rows above the form, with a link across to Publishing for the full picture.

Checked

Before anything leaves Nova, it checks three things that would stop the publish working: that your API key can reach the project space you picked, that the app itself has nothing outstanding, and that the project space supports the app features that need destination support. If any required support is missing, or Nova cannot confirm it, nothing is sent. The result names the capability and the next step.

Nova also reports useful guidance that does not stop the publish. For example, the project space may be able to run the app while large Search results open more slowly, or a persona may be missing worker information that CommCare HQ will ask for later. Read Project-space compatibility for the complete check.

Data in place

Two things go on the project space before the app does, because the app reaches for them by name while somebody is using it. An app that arrived first would install and then misbehave.

This step only appears when your app has one of them.

Lookup tables. If your app reads any lookup tables, Nova puts them there and replaces their rows with the rows in Nova. Tables your app does not read are left alone.

Places. If your app has an organization, Nova creates and updates its places there, working down from the top so each one can name the place above it. It sends every place that is not archived, along with whatever place information you filled in.

If something of that name is already there and Nova did not make it, Nova stops rather than write over it, and names it. CommCare HQ matches a lookup table on its export tag and a place on its site code, and two things could be true: it is yours, from before you used Nova, or it belongs to something else on that project space. Nova cannot tell, so you choose. Tick the ones that are yours and publish again, and Nova will keep them up to date from then on. Leave one unticked and it stays exactly as it is.

Nova cannot make organization levels, so if your places stand at levels the project space does not have, or your organization skips a rung the project space insists on, publishing stops and names each place. Add the levels on CommCare HQ first; the list Nova gives you after a publish has them all, in order.

Renaming a table's export tag makes a new table on CommCare HQ. The old one stays where it is, so nothing anybody else built on it breaks, and Nova names it so you can delete it there when you no longer need it. Archiving a place works the same way: Nova stops sending it and names it, and the one on CommCare HQ stays exactly where it is, because CommCare HQ's API has no way to archive or delete a place.

On CommCare HQ

Your app is now on the project space. It is not something workers can open yet.

Publishing again updates this same app in place, name included, so the project space keeps one app that tracks what you build in Nova. The one exception: if the app was deleted on CommCare HQ since Nova put it there, Nova tells you so when you try, and publishing once more creates a fresh one.

Immediately before an update, Nova reads the current CommCare HQ app and keeps destination-specific behavior it does not own. If that app cannot be read safely, Nova leaves the existing HQ app unchanged instead of guessing what to keep.

Nova never deletes anything on CommCare HQ. So when a publish stops pointing at something it put there before, whether that is an app it replaced or a lookup table whose tag you renamed, Nova names it and leaves it to you. A table is named by the tag it still carries on CommCare HQ, which is what you will look for on the Lookup Tables screen. Nothing appears here for a table you simply republished, only for one nothing in your app points at any more.

Version made, and Released

On CommCare HQ, open your app and go to Releases. Choose Make new version, wait for it to finish, then star the new version to release it.

Nova cannot do these two for you. CommCare HQ accepts an API key for putting an app on a project space but not for building or releasing one, so these are yours to do there. Nova watches for them instead.

CommCare HQ validates the app again while it builds. If it reports errors there, they are about the version you just published: fix them in Nova and publish again.

Ready for workers

Once a version is released, Nova checks that it actually serves the file a device installs from. That is the strongest sign it will open for workers, and the only one of the five steps Nova can confirm rather than take on trust.

The Open in CommCare HQ link appears as soon as the app is there, and it goes to the app's page for you to work on. It is not the link workers use.

Making workers

Publishing sends an app. It does not create anybody an account, because handing out a credential is not something to do by accident.

Once the app is on a project space, that project space's card in App setup → Publishing has a Workers list, one row per persona. Tick the ones you want, adjust the username Nova suggests, and choose Make workers. Each account carries that persona's worker information and the places it stands in.

Every new account comes with a password, shown once. Copy them before you leave the page. Nova keeps no copy, so a password you lose has to be reset on CommCare HQ.

Ticking a persona that already has an account brings that account into step with what the app says now, rather than making a second one. Its password is untouched.

Occasionally CommCare HQ breaks off partway through making an account without saying whether it made one. Nova shows that row with the other passwords, marked May not exist, and keeps it on screen through everything you do next. Copy it anyway: if the account turned out to be real, that is the only password it will ever have. Then look for that username on your project space. If it isn't there, choose Make workers again. If it is, give CommCare HQ a moment to notice its own new account first, and then Make workers offers you the one already there.

Three things Nova will refuse rather than guess at:

• A username somebody already has. Nova shows you the account and takes it over only if you say so for that exact one. A shared name is not evidence it is yours.
• A persona missing worker information you marked required. CommCare HQ will not save a worker without it. Publishing still works; only making the worker stops.
• A persona standing in a place that is not on the project space yet. Publish the app there first, which puts the places there.

Nova never deletes or retires a worker, because CommCare HQ's own delete also deletes every case that worker owns. Remove a persona and its account is reported as left behind, still there for you to deal with on CommCare HQ.

What you set up by hand

Some of what your app needs lives on the project space rather than in the app, and CommCare HQ has no way for Nova to create it. After you publish, Nova lists exactly what those are, with a link to the right page on your project space and the values already filled in.

• Worker information. One field per piece of information your workers carry, on the project's user-data page. Do this before you make workers: CommCare HQ validates a worker's information against these fields.
• Roles. Nova does not create CommCare user roles. A worker Nova makes has no role until you give it one.
• Organization levels. The rungs of your organization. Create these before you publish, because every place names the level it stands at and CommCare HQ will not take a place whose level is not there.
• Place information. One field per piece of information your places carry, on the project's location-fields page. Nova sends the values with every place; a field the project space has not defined is kept as loose data that nothing on CommCare HQ can validate or filter on.
• Automations. Each rule or alert, created on the relevant page. Changing an automation in Nova does not change one you already made on CommCare HQ.

These notes are generated fresh every time you look at them, so they always match your app as it is now.

If something goes wrong

A publish that could not finish says so plainly, names what stopped it, and remembers where it stopped.

What to do next depends on where it stopped, and Nova says which:

• Before the app reached CommCare HQ (a connection problem, something in the app itself, or a table or place Nova would not write over): fix it and publish again. A publish that stopped on the data never sent the app, so trying again picks up from there. Places go out in groups, one level at a time, and each group either lands whole or not at all, so a publish that stopped partway left the groups above it in place and the next one carries on from there rather than making a second copy.
• After it got there (a version that would not build, a release Nova could not confirm): the app is already on your project space. Sort it out on CommCare HQ, then choose Check status; there is no need to publish again.

A note on Web Apps

CommCare HQ sets an app's Web App setting when the app is created, from whether your project had Web Apps at that moment. So an app published before the feature was turned on starts with it off, and will not appear in Web Apps even once it is released.

If that happens, open the app's Settings on CommCare HQ and tick Web App. You do not need to publish again.