@uio-appu/mobile-nettskjema-js

Utility library for interacting with Nettskjema from React-Native. Provides an API for fetching forms, creating submissions from key-value dictionaries of codebook values and delivering to Nettskjema.

This libary also exports a Queue service that can keep track of, deliver, and locally delete submissions, while keeping the submissions locally encrypted in the app's storage area.

Installation

1. Install dependencies yarn add @uio-appu/mobile-nettskjema-js react-native-keychain @react-native-community/netinfo react-native-get-random-values react-native-fs

• If you are not going to deliver attachments/files to Nettskjema, you can add the following to your react-native.config.js to disable autolinking the native MNJS code for file encryption:

module.exports = {
  dependencies: {
    '@uio-appu/mobile-nettskjema-js': {
      platforms: {
        android: null,
        ios: null,
      },
    },
  },
};

2. Install cocoapods dependencies npx pod-install (if you are using attachment delivery, modify the Podfile as described below first)

If you are going to deliver attachments, do also:

1. Add kotlinVersion = "1.6.21" to your app/build.gradle-file (below minimumSdkVersion) and set minimumSdkVersion = 23 (or higher).
2. Set the minimum iOS version to 13 (or higher) in ios/Podfile and for the project's Xcode settings.
3. Install cocoapod dependencies npx pod-install

Notes:

• The library might not work on RN <0.68, and might require upgrading RN to a more recent version.
• The minimum SDK has to be at least 23, and iOS version has to be at least 13 in order for the file encryption for attachments to work properly.

Setup

If you want to use the built in delivery queue do the following:

After installing, wrap your app with the NettskjemaProvider and supply it with a statically defined instance of NettskjemaQueue.

  import { NettskjemaQueue } from '@uio-appu/mobile-nettskjema-js';

  export const queue = new NettskjemaQueue();
  const WrappedApp = () => {
    return (
      <NettskjemaProvider queue={queue}>
        <MyApp />
      </NettskjemaProvider>
    );
  };

This will automatically initialize the delivery queue, and make it available in the app's context. You can then import and use useQueue and useQueuedSubmissions to get access to the queue and its data.

Examples

Fetching form

import {formSpecification} from '@uio-appu/mobile-nettskjema-js';

const getForm = async (formId) => {
  try {
    const formSpec = await formSpecification(formId);
    return formSpec;
  } catch (error) {
    console.error(error.message); // Form was set up incorrectly or failed to fetch
  }
}

Creating submission

  import {submissionCreator} from '@uio-appu/mobile-nettskjema-js';

  const createSubmission = (formSpec, answers) => {
    try {
      const submission = submissionCreator(formSpec)(answers);
      return submission;
    } catch (error) {
      console.error(error.message); // Malformed or invalid answers (missing required answers, number in number field too high or low, etc.)
    }
  };

Delivering submission with Queue

  import {useQueue} from '@uio-appu/mobile-nettskjema-js';
  const DeliverButton = ({submission}) => {
    const [queue] = useQueue();
    return <Button onPress={() => {queue.add(submission)}} />;
  };

Once the submission is added to the queue, it will by default try to deliver it to Nettskjema. If it fails, it is up to the app to routinely call queue.deliverAll() to deliver all undelivered submissions. Could be triggered when the app comes in to focus, or you can let the user trigger manual delivery of specific submissions (especially if the user is delivering large files manually).

Auto submission preference can also be changed by calling queue.setAutoSubmissionPreference() with the values 'NEVER' or 'ONLY_WITH_WIFI' ('ALWAYS' is the default) every time the queue is set up. ONLY_WITH_WIFI will only attempt delivery if @react-native-community/netinfo is installed and wifi is connected when the submission is added to the queue (manually triggering delivery using deliverAll or _deliverSingle ignores auto submission preference).