Questionnaire Panel

    Suggestions will appear below the field as you type

    Questionnaire Panel

      Suggestions will appear below the field as you type

      Questionnaire Panel

      Questionnaire Panel

      SEEK provides a Questionnaire Panel you can embed within your job posting flow. The Questionnaire Panel allows hirers to interactively create questionnaires for candidates to complete as part of their job application. It lets hirers:
      • Select relevant question suggestions from SEEK’s library of commonly used questions to ask candidates as a part of their job application.
        The relevancy of the questions to the hirers’ role will depend on the position’s title, job category, location, advertisement details, search summary, and search bullet points that are inputted.
      • Add custom questions if they do not find the suggestions from SEEK’s library to be relevant.
      • Select preferred answers for each question.
      • Attach a company privacy policy if applicable.

      Browser support

      The Questionnaire Panel tracks our standard browser support policy.

      Step 1: Include the panel

      Add the following script tag to the page where you want to insert the Questionnaire Panel:
      HTML
      Copy
      <script
        type="text/javascript"
        src="https://seekcdn.com/hirer/indirect-posting/questionnaire-panel/SEEKQuestionnairePanel.js"
      ></script>

      Step 2: Render the panel

      The render method renders an instance of the panel in the specified DOM element.
      The render method must be called on page load and whenever the properties of the positionProfile object change. For example, if the hirer updates their position title you must call render to refresh question suggestions.
      The render function may throw errors if:
      • The containerNode provided is not a valid HTMLElement
      • The options you provide are incorrect

      Example JavaScript

      JavaScript
      Copy
      SEEKQuestionnairePanel.render(containerNode, options);
      • containerNode – (DOM Node) The DOM element to render the panel into.
      • options – Options for rendering the panel; see options below.

      Options

      Option property
      Type
      Description
      getAuthToken
      () => Promise<string>
      Function to call to retrieve the browser token to use when calling the SEEK API.
      errorHandler
      ({ errors: object[] }) => void
      optional
      You may provide your own errorHandler in order to monitor errors being generated by hirers as they use the Questionnaire Panel. If nothing is provided, errors are printed with console.error.
      schemeId
      string
      The scheme ID to use when suggesting questions or creating questionnaires. Either seekAnz or seekAnzPublicTest.
      mode
      string
      The mode of the panel. Set to Create when posting a new job ad, and Update when updating an existing job ad. The widget will show a non-editable summary of the questionnaire in update mode.
      questionnaireId
      string
      optional
      The ID of an existing questionnaire to load into the panel. Questionnaires are immutable; once saved they cannot be edited.
      privacyPolicy
      object
      optional
      The configuration options for the hirer’s privacy policy. The option to include a privacy policy question will only be presented to the hirer if this is present.
      privacyPolicy.url
      string
      The website where the hirer’s privacy policy is hosted.
      privacyPolicy.descriptionHtml
      string
      optional
      A short phrase to present to candidates to prompt them to accept the privacy policy. Defaults to “Do you agree to the privacy policy?”
      positionProfile
      object
      The configuration options for providing information about the position being posted. This information is used to suggest questions relevant to the position.
      positionProfile.jobCategories
      string[]
      optional
      The array of identifiers for the position’s job category. Only a single value is currently accepted.
      positionProfile.positionLocation
      string[]
      optional
      The array of identifiers for the position’s location. Only a single value is currently accepted.
      positionProfile.positionOrganizations
      string[]
      The array of identifiers of the hirer posting the job. Only a single value is currently accepted.
      positionProfile.positionTitle
      string
      optional
      The title of the position.
      positionProfile.positionFormattedDescriptions
      object[]
      optional
      An array of formatted position profile descriptions.
      positionProfile.positionFormattedDescriptions[].content
      string
      The HTML content of the description.
      positionProfile.positionFormattedDescriptions[].descriptionId
      string
      The description type. One of AdvertisementDetails, SearchBulletPoint, or SearchSummary.
      ErrorResult
      The errorHandler configured in the options is provided with an array of ErrorResult objects when something goes wrong with the Questionnaire Panel. The information is generally not useful to hirers, as the panel itself will show the hirer a message for any problems they can fix themselves.
      ErrorResult property
      Type
      Description
      errorCode
      string
      One of the SEEK API’s error responses.
      message
      string
      A description of what the problem is.
      ErrorResult examples
      INTERNAL_SERVER_ERRORBAD_USER_INPUTUNAUTHENTICATEDFORBIDDEN
      Copy
      {
        "errorCode": "INTERNAL_SERVER_ERROR",
        "message": "[Network error]: TypeError: Network request failed"
      }

      Sample code

      JavaScript
      Copy
      try {
        SEEKQuestionnairePanel.render(
          document.getElementById('seekQuestionnaireContainerDiv'),
          {
            // Function to call to retrieve the browser token to use when calling the
            // SEEK API, see "Step 3" for more details.
            getAuthToken: () => {
              return Promise.resolve('browser token');
            },
            // You may provide an errorHandler to log any errors that occur with the Questionnaire Panel.
            errorHandler: ({ errors }) => {
              logErrors(errors);
            },
            // The schemeId controls whether the panel talks to the live production
            // environment or the Playground environment.
            schemeId: 'seekAnzPublicTest',
            // The mode controls whether the panel allows edits to the questionnaire.
            // Questionnaires are immutable, and cannot be added to or removed from a
            // posted job ad.
            mode: 'Create',
            // Providing a questionnaire ID will make the panel load the data from that
            // questionnaire. If the questionnaire was saved as part of a draft job
            // ad and the mode is still `Create`, the widget will allow the hirer to
            // add and remove questions.
            questionnaireId:
              'seekAnzPublicTest:applicationQuestionnaire:rrv2:SqFmkV8S2dMipyqbHjD9Mr',
            // The privacy policy allows you to configure how a hirer‘s privacy policy
            // may be attached.
            privacyPolicy: {
              url: 'https://example.com/privacy-policy.html',
              descriptionHtml: 'Do you accept the terms in the privacy policy?'
            },
            // The positionProfile allows you to add the details of the position being
            // posted to improve question suggestions.
            positionProfile: {
              jobCategories: 'seekAnzPublicTest:jobCategory:seek:27HXTkNXh',
              positionLocation: 'seekAnzPublicTest:location:seek:W7NggeKH',
              positionOrganizations: 'seekAnzPublicTest:organization:seek:E2LikAHu',
              positionTitle: 'Office Manager',
              positionFormattedDescriptions: [
                {
                  content:
                    '<strong>Amazing opportunity!</strong><p>Do you want to join a fast-paced company, managing the office and staff?</p>',
                  descriptionId: 'AdvertisementDetails'
                },
                {
                  content: 'Great culture',
                  descriptionId: 'SearchBulletPoint'
                },
                {
                  content: 'Exciting role fronting a dynamic office',
                  descriptionId: 'SearchSummary'
                }
              ]
            }
          }
        );
      } catch (error) {
        // Errors thrown here might be caused by not providing a valid HTMLElement as
        // the containerNode, a configuration error in your options, or by the
        // Questionnaire Panel script not successfully loading.
      }

      Step 3: Handle browser token requests

      1. The panel loads and invokes the getAuthToken function passed to it.
      2. Your frontend requests a browser token from your backend.
        The getAuthToken function should request a new token for the hirer ID in positionProfile.positionOrganizations. If a user switches to a different SEEK hirer account in your posting form, your software should re-render the panel with the new hirer ID in positionProfile.positionOrganizations, and ensure that subsequent invocations of getAuthToken will request a token for the new hirer ID.
      3. Your backend authenticates and authorises the user.
        Your software is responsible for verifying that the user is authorised to access a given hirer ID. A user must not be able to request a browser token for an arbitrary organization that they do not belong to.
      4. Your backend requests a browser token from the SEEK API for the appropriate hirer ID and mutate:application-questionnaires query:application-library-question-suggestions query:application-questionnaires query:organizations scope.
      5. Your backend responds with the browser token.
      6. Your frontend returns the browser token from the getAuthToken function.
      7. The panel can now make requests to the GraphQL endpoint.
      HTTP
      Copy
      POST https://graphql.seek.com/auth/token HTTP/1.1
      Authorization: Bearer PARTNER_TOKEN_HERE
      Content-Type: application/json
      User-Agent: YourPartnerService/1.2.3
      {
        "hirerId": "seekAnzPublicTest:organization:seek:93WyyF1h",
        "scope": "mutate:application-questionnaires query:application-library-question-suggestions query:application-questionnaires query:organizations",
        "userId": "317665"
      }

      Step 4: Post the job ad

      When the hirer is ready to post their job ad, your software should call SEEKQuestionnairePanel.save(). It returns a Promise to a result object. SEEKQuestionnairePanel.save() does not throw exceptions.

      Result object

      Result property
      Type
      Description
      errorCode
      string | null
      If an error has occurred, a code is returned indicating the nature of the problem. One of BAD_USER_INPUT, INTERNAL_SERVER_ERROR, UNAUTHENTICATED, or FORBIDDEN.
      data
      object | null
      An object that contains information about the saved questionnaire.
      Only present when questions were configured in the panel and errorCode is null.
      data.id
      string
      The questionnaire ID of the saved questionnaire. For example, seekAnzPublicTest:applicationQuestionnaire:rrv2:SqFmkV8S2dMipyqbHjD9Mr.
      If the save succeeded, then errorCode will be null, and data.id will contain the saved questionnaire’s ID. You may provide the new questionnaire ID in the PostPosition_PositionProfileInput.seekApplicationQuestionnaireId  and PostPositionProfileForOpeningPositionProfileInput.seekApplicationQuestionnaireId  mutation inputs, or persist it as part of a draft job ad.
      If the hirer did not add any questions via the panel, then errorCode will be null, and data will be null. You should continue to post the job ad without a questionnaire ID.
      If there was some problem with the questions the hirer added—for example, adding a custom question, but not configuring any answers—then the errorCode will be BAD_USER_INPUT, and data will be null. You should not continue to post the job ad, as the hirer intends to add a questionnaire but has made a correctable error.
      If the token the panel receives from the configured getAuthToken option is expired or invalid, then errorCode will be UNAUTHENTICATED. If the token was issued to a different hirer than what is included in positionProfile.positionOrganizations, then errorCode will be FORBIDDEN. For all other errors, including network connectivity issues, the errorCode will be INTERNAL_SERVER_ERROR.
      In all these error scenarios, data will be null. You should not continue to post the job ad, as the hirer has intended to add a questionnaire, but there has been a fatal error.
      JavaScript
      Copy
      const postSeekJobAd = async (input) => {
        // Call a posting mutation to post or update a SEEK job ad.
      };
      
      
      const handleSubmitButton = async () => {
        const input = {
          // Compose from form data.
        };
      
      
        const result = await SEEKQuestionnairePanel.save();
      
      
        if (result.errorCode) {
          // Do not post the job ad if an error occurs while saving the questionnaire.
          // The panel will display an error message to the hirer.
          return;
        }
      
      
        // Data will be nullish if the hirer did not add any questions via the panel.
        if (result.data?.id) {
          input.positionProfile.seekApplicationQuestionnaireId = result.data.id;
        }
      
      
        await postSeekJobAd(input);
      };

      Draft job ads

      If your software supports draft job ads, you should also save the questionnaire state as part of the draft. Saving a questionnaire for a draft works the same way as saving for posting a job ad. Call SEEKQuestionnairePanel.save(), and if there is a returned questionnaire ID and no errorCode, then continue to save the draft, persisting the new questionnaire ID returned. To load the draft into the Questionnaire Panel, you must provide the saved questionnaireId and set the mode to Create in the panel options.