Package edu.internet2.middleware.grouper.app.freshServiceRequester

Class FreshRequesterApiCommands

java.lang.Object
edu.internet2.middleware.grouper.app.freshServiceRequester.FreshRequesterApiCommands
public class FreshRequesterApiCommands extends Object

  • Field Details

    • doNotLogParameters

      public static final Set<String> doNotLogParameters

    • doNotLogHeaders

      public static final Set<String> doNotLogHeaders

    • grouperLoaderConfig

      public static GrouperLoaderConfig grouperLoaderConfig

  • Constructor Details

    • FreshRequesterApiCommands

      public FreshRequesterApiCommands()

  • Method Details

    • main

      public static void main(String[] args)

    • createRequesterGroup

      public static FreshRequesterGroup createRequesterGroup(String configId, FreshRequesterGroup grouperRequesterGroup)
      Create a requester group in Freshservice
      Parameters:
      configId - the id of the external system
      grouperRequesterGroup - the requester group to be created in Freshservice

    • updateRequesterGroup

      public static FreshRequesterGroup updateRequesterGroup(String configId, FreshRequesterGroup grouperRequesterGroup, Map<String,ProvisioningObjectChangeAction> fieldsToUpdate)
      Update a Freshservice requester group
      Parameters:
      configId - the id of the external system
      grouperRequesterGroup - the group to be updated in Freshservice

    • updateRequesterUser

      public static FreshRequesterUser updateRequesterUser(String configId, FreshRequesterUser grouperRequesterUser, Set<String> fieldsToUpdate)
      Update a Freshservice requester user. This method performs a three-step update: 1. GET the current requester JSON from Freshservice by id 2. Strip read-only attributes that cannot be sent on a PUT (id, created_at, has_logged_in, is_agent, updated_at, work_schedule_id, department_names, location_name) 3. Overlay the fields indicated in fieldsToUpdate with values from the supplied FreshRequesterUser, then PUT the result The fieldsToUpdate set uses Java-style field names which are translated to their Freshservice JSON attribute names (e.g. "firstName" becomes "first_name", "email" becomes "primary_email", "departmentId" becomes "department_ids" array). Custom fields use the prefix "customField_" followed by the Freshservice custom field name (e.g. "customField_pennkey").
      Parameters:
      configId - the id of the external system
      grouperRequesterUser - the requester user containing the new values. Must have id set to identify which user to update.
      fieldsToUpdate - set of Java field names to update. Supported values: "firstName", "lastName", "email", "jobTitle", "workPhoneNumber", "departmentId", "reportingManagerId", "address", "active", and custom fields with prefix "customField_" (e.g. "customField_pennkey")
      Returns:
      the updated requester user parsed from the PUT response

    • deleteRequesterGroup

      public static void deleteRequesterGroup(String configId, Long groupId)
      Delete a requester group
      Parameters:
      configId - the id of the external system
      groupId - the id of the group to be deleted

    • retrieveRequesterGroup

      public static FreshRequesterGroup retrieveRequesterGroup(String configId, Long id)
      Get a Freshservice requester group
      Parameters:
      configId - the id of the external system
      id - the requester group id
      Returns:
      the GrouperRequesterGroup matching the Freshservice group retrieved

    • retrieveRequesterGroups

      public static List<FreshRequesterGroup> retrieveRequesterGroups(String configId)
      Get a list of all Freshservice requester groups
      Parameters:
      configId - the id of the external system
      Returns:

    • createRequesterUser

      public static FreshRequesterUser createRequesterUser(String configId, FreshRequesterUser grouperRequesterUser)
      Create a requester user in Freshservice, or update an existing one if a user with the same email address already exists. This method first looks up the user by email address: - If a user already exists and is inactive, it will be reactivated and updated with all the fields from grouperRequesterUser. - If a user already exists and is active, it will be updated with all the fields from grouperRequesterUser. - If no user exists with that email, a new user is created via the helper method.
      Parameters:
      configId - the id of the external system
      grouperRequesterUser - the user to be created or updated in Freshservice
      Returns:
      the created or updated requester user

    • createRequesterUserHelper

      public static FreshRequesterUser createRequesterUserHelper(String configId, FreshRequesterUser grouperRequesterUser)
      Helper method to create a new requester user in Freshservice via POST. This method directly calls the Freshservice POST /api/v2/requesters endpoint. Callers should typically use createRequesterUser() which handles the lookup-by-email and update-if-exists logic.
      Parameters:
      configId - the id of the external system
      grouperRequesterUser - the user to be created in Freshservice
      Returns:
      the created requester user with assigned id

    • retrieveRequesterUsers

      public static List<FreshRequesterUser> retrieveRequesterUsers(String configId, boolean includeInactiveRequesters)
      Retrieve all requester users from Freshservice
      Parameters:
      configId - the id of the external system
      includeInactiveRequesters - if true, include inactive (deactivated) requesters in the results. If false, only active requesters are returned.
      Returns:
      a list of Freshservice requester users

    • retrieveRequesterUserById

      public static FreshRequesterUser retrieveRequesterUserById(String configId, Long id, boolean includeInactiveRequesters)
      Get a Freshservice requester user by id
      Parameters:
      configId - the id of the external system
      id - the id of the requester user to be retrieved
      includeInactiveRequesters - if true, return the user even if inactive. If false, return null for inactive users.
      Returns:
      the requester user, or null if not found (or inactive when not included)

    • retrieveRequesterUserByEmail

      public static FreshRequesterUser retrieveRequesterUserByEmail(String configId, String email, boolean includeInactiveRequesters)
      Get a Freshservice requester user by email address. Uses the Freshservice email parameter: GET /api/v2/requesters?email=jsmith@upenn.edu
      Parameters:
      configId - the id of the external system
      email - the email address of the requester user to be retrieved
      includeInactiveRequesters - if true, return the user even if inactive. If false, return null for inactive users.
      Returns:
      the requester user, or null if not found (or inactive when not included)

    • retrieveRequesterUserByAttribute

      public static FreshRequesterUser retrieveRequesterUserByAttribute(String configId, String attributeName, Object attributeValue)
      Retrieve a requester user by a provisioning attribute name and value. If attributeName is "id" or "email", delegates to the existing lookup methods. If attributeName is "externalId", searches by external_id. If attributeName starts with "customField_", searches by that custom field name. Otherwise throws an exception. The Freshservice API query format is: GET /api/v2/requesters?query=attributeName:'value' (for strings) GET /api/v2/requesters?query=attributeName:value (for numbers)
      Parameters:
      configId - the id of the external system
      attributeName - the provisioning attribute name (e.g. "id", "email", "externalId", "customField_pennkey")
      attributeValue - the value to search for. Must be String, Long, or Integer. String values are always quoted in the query (even if they contain digits). Long/Integer values are sent as bare numbers.
      Returns:
      the requester user if found, null if not found
      Throws:
      RuntimeException - if multiple users are found or attributeValue is an unsupported type

    • addGroupMembership

      public static void addGroupMembership(String configId, Long groupId, Long userId)
      Add a requester user to a group.
      Parameters:
      configId - the id of the external system
      groupId - the id of the group gaining a member user
      userId - the id of the new group member user

    • removeGroupMembership

      public static void removeGroupMembership(String configId, Long groupId, Long userId)
      Remove a requester user from a group.
      Parameters:
      configId - the id of the external system
      groupId - the id of the group losing a member user
      userId - the id of the group member user to remove

    • retrieveMembershipsByGroup

      public static List<FreshRequesterUser> retrieveMembershipsByGroup(String configId, Long groupId)
      Retrieve the members of a group
      Parameters:
      configId - the id of the external system
      groupId - the id of the group to get members from
      Returns:
      list of requester users who are members of the group

    • deactivateRequesterUser

      public static void deactivateRequesterUser(String configId, Long userId)
      Deactivate (delete) a requester user in Freshservice. Endpoint: DELETE /api/v2/requesters/{id} Expected response: 204 No Content (sometimes 200/404 depending on Freshservice behavior)
      Parameters:
      configId - the id of the external system
      userId - the requester user id

    • reactivateRequesterUser

      public static void reactivateRequesterUser(String configId, Long userId)
      Reactivate a deactivated requester user in Freshservice. Endpoint: PUT /api/v2/requesters/{id}/reactivate Returns 200 if successful. 400 with body if already active: {"code":"contact_already_active","message":"Contact is already active and cannot be restored."}
      Parameters:
      configId - the id of the external system
      userId - the requester user id

    • forgetRequesterUser

      public static void forgetRequesterUser(String configId, Long userId)
      Permanently delete (forget) a requester user from Freshservice. This removes the user entirely, unlike deactivate which just sets active=false. Endpoint: DELETE /api/v2/requesters/{id}/forget Expected response: 204 No Content, 404 if already deleted
      Parameters:
      configId - the id of the external system
      userId - the requester user id