node-behind-api-client 2.0.48

package/docs/behind-api-client/easyjob/jd-candidate-questions/README.md

@@ -0,0 +1,372 @@
+# Job Description Candidate Questions API Extension
+
+This document extends the main EasyJob JavaScript API Client Documentation with detailed information about the Job Description Candidate Questions API methods.
+
+## Overview
+
+The Job Description Candidate Questions API allows you to manage custom questions that can be asked to candidates applying for specific job positions. These questions can be categorized and weighted based on their importance to the hiring process.
+
+---
+
+## Job Description Candidate Questions API
+
+### behindAPI.easyjob.V10.jobDescriptionCandidateQuestions.create(jobDescriptionId, question, type, weight, category)
+Creates a new candidate question for a job description.
+
+**Parameters:**
+- `jobDescriptionId` (string, required) - The job description UUID where the question belongs
+- `question` (string, required) - The question text
+- `type` (string, required) - The question type. Valid values: `"binary_check"`, `"open_response"`, `"short_answer"`, `"integer"`
+- `weight` (integer, required) - The question weight (numeric value indicating importance)
+- `category` (string, required) - The question category. Valid values: `"custom"`, `"basic"`
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.jobDescriptionCandidateQuestions.create(
+  "770e8400-e29b-41d4-a716-446655440002",
+  "How many years of experience do you have with React?",
+  "integer",
+  5,
+  "custom"
+);
+
+// Response:
+{
+  success: true,
+  data: {
+    question_id: "cc0e8400-e29b-41d4-a716-446655440007"
+  }
+}
+```
+
+### behindAPI.easyjob.V10.jobDescriptionCandidateQuestions.delete(questionId)
+Deletes a specific candidate question by its ID.
+
+**Parameters:**
+- `questionId` (string, required) - The question UUID to delete
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.jobDescriptionCandidateQuestions.delete("cc0e8400-e29b-41d4-a716-446655440007");
+
+// Response:
+{
+  success: true
+}
+```
+
+### behindAPI.easyjob.V10.jobDescriptionCandidateQuestions.deleteAll(jobDescriptionId)
+Deletes all candidate questions for a specific job description.
+
+**Parameters:**
+- `jobDescriptionId` (string, required) - The job description UUID to delete all questions for
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.jobDescriptionCandidateQuestions.deleteAll("770e8400-e29b-41d4-a716-446655440002");
+
+// Response:
+{
+  success: true
+}
+```
+
+### behindAPI.easyjob.V10.jobDescriptionCandidateQuestions.getList(jobDescriptionId)
+Retrieves all candidate questions for a specific job description.
+
+**Parameters:**
+- `jobDescriptionId` (string, required) - The job description UUID to get questions for
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.jobDescriptionCandidateQuestions.getList("770e8400-e29b-41d4-a716-446655440002");
+
+// Response:
+{
+  success: true,
+  data: [
+    {
+      question_id: "cc0e8400-e29b-41d4-a716-446655440007",
+      job_description_id: "770e8400-e29b-41d4-a716-446655440002",
+      question: "How many years of experience do you have with React?",
+      type: "integer",
+      weight: 5,
+      category: "custom",
+      created_at: "2024-01-15T10:30:00Z",
+      updated_at: "2024-01-15T10:30:00Z"
+    }
+  ]
+}
+```
+
+### behindAPI.easyjob.V10.jobDescriptionCandidateQuestions.getByCategory(jobDescriptionId, category)
+Retrieves candidate questions for a specific job description filtered by category.
+
+**Parameters:**
+- `jobDescriptionId` (string, required) - The job description UUID to get questions for
+- `category` (string, required) - The category to filter by. Valid values: `"general"`, `"custom"`, `"basic"`
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.jobDescriptionCandidateQuestions.getByCategory(
+  "770e8400-e29b-41d4-a716-446655440002",
+  "custom"
+);
+
+// Response:
+{
+  success: true,
+  data: [
+    {
+      question_id: "cc0e8400-e29b-41d4-a716-446655440007",
+      job_description_id: "770e8400-e29b-41d4-a716-446655440002",
+      question: "How many years of experience do you have with React?",
+      type: "integer",
+      weight: 5,
+      category: "custom",
+      created_at: "2024-01-15T10:30:00Z",
+      updated_at: "2024-01-15T10:30:00Z"
+    }
+  ]
+}
+```
+
+### behindAPI.easyjob.V10.jobDescriptionCandidateQuestions.edit(questionId, text, weight)
+Edits an existing candidate question.
+
+**Parameters:**
+- `questionId` (string, required) - The question UUID to edit
+- `text` (string, optional) - The new question text
+- `weight` (integer, optional) - The new question weight
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.jobDescriptionCandidateQuestions.edit(
+  "cc0e8400-e29b-41d4-a716-446655440007",
+  "How many years of professional experience do you have with React development?",
+  7
+);
+
+// Response:
+{
+  success: true
+}
+```
+
+---
+
+## Data Types and Constraints
+
+### Question Types
+- **`binary_check`** - Yes/No or True/False questions
+- **`open_response`** - Long-form text responses
+- **`short_answer`** - Brief text responses
+- **`integer`** - Numeric responses
+
+### Question Categories
+- **`general`** - Standard questions applicable to most positions (only available for filtering)
+- **`custom`** - Job-specific questions tailored to the position
+- **`basic`** - Fundamental screening questions
+
+**Note:** When creating questions, only `"custom"` and `"basic"` categories are allowed.
+
+### Weight System
+- Question weights are integer values that indicate the relative importance of each question
+- Higher weights typically indicate more critical questions in the evaluation process
+- Weight values can be any positive integer
+- Default weight is 0 if not specified
+
+---
+
+## Complete Usage Example
+
+```javascript
+// Complete workflow for managing candidate questions
+async function setupCandidateQuestions(jobDescriptionId) {
+  try {
+    // 1. Create basic screening questions
+    const basicQuestions = [
+      {
+        question: "Are you legally authorized to work in this country?",
+        type: "binary_check",
+        weight: 10,
+        category: "basic"
+      },
+      {
+        question: "Are you willing to relocate if necessary?",
+        type: "binary_check",
+        weight: 3,
+        category: "basic"
+      }
+    ];
+
+    // 2. Create technical questions
+    const technicalQuestions = [
+      {
+        question: "Describe your experience with microservices architecture",
+        type: "open_response",
+        weight: 8,
+        category: "custom"
+      },
+      {
+        question: "How many years of experience do you have with Node.js?",
+        type: "integer",
+        weight: 6,
+        category: "custom"
+      },
+      {
+        question: "What is your preferred development methodology?",
+        type: "short_answer",
+        weight: 4,
+        category: "custom"
+      }
+    ];
+
+    // 3. Create general questions
+    const generalQuestions = [
+      {
+        question: "Why are you interested in this position?",
+        type: "open_response",
+        weight: 5,
+        category: "custom"
+      },
+      {
+        question: "What are your salary expectations?",
+        type: "short_answer",
+        weight: 2,
+        category: "custom"
+      }
+    ];
+
+    // Create all questions
+    const allQuestions = [...basicQuestions, ...technicalQuestions, ...generalQuestions];
+    const createdQuestions = [];
+
+    for (const q of allQuestions) {
+      const result = await behindAPI.easyjob.V10.jobDescriptionCandidateQuestions.create(
+        jobDescriptionId,
+        q.question,
+        q.type,
+        q.weight,
+        q.category
+      );
+      
+      if (result.success) {
+        createdQuestions.push(result.data.question_id);
+        console.log(`Created question: ${q.question}`);
+      }
+    }
+
+    // 4. Retrieve and display questions by category
+    const customQs = await behindAPI.easyjob.V10.jobDescriptionCandidateQuestions.getByCategory(
+      jobDescriptionId, 
+      "custom"
+    );
+    console.log(`Created ${customQs.data.length} custom questions`);
+
+    const basicQs = await behindAPI.easyjob.V10.jobDescriptionCandidateQuestions.getByCategory(
+      jobDescriptionId, 
+      "basic"
+    );
+    console.log(`Created ${basicQs.data.length} basic questions`);
+
+    // 5. Get complete list of all questions
+    const allQsList = await behindAPI.easyjob.V10.jobDescriptionCandidateQuestions.getList(jobDescriptionId);
+    console.log(`Total questions created: ${allQsList.data.length}`);
+
+    // 6. Edit a question if needed
+    if (createdQuestions.length > 0) {
+      await behindAPI.easyjob.V10.jobDescriptionCandidateQuestions.edit(
+        createdQuestions[0],
+        "Are you legally authorized to work in the United States?", // Updated text
+        10 // Keep same weight
+      );
+      console.log("Updated first question");
+    }
+
+    console.log("Candidate questions setup completed successfully!");
+    return createdQuestions;
+
+  } catch (error) {
+    console.error("Error setting up candidate questions:", error);
+    return [];
+  }
+}
+
+// Example: Clean up questions for a job description
+async function cleanupQuestions(jobDescriptionId) {
+  try {
+    // Delete all questions for the job description
+    const result = await behindAPI.easyjob.V10.jobDescriptionCandidateQuestions.deleteAll(jobDescriptionId);
+    
+    if (result.success) {
+      console.log("All questions deleted successfully");
+    } else {
+      console.log("Failed to delete questions");
+    }
+    
+  } catch (error) {
+    console.error("Error cleaning up questions:", error);
+  }
+}
+
+// Example: Selective question management
+async function manageQuestions(jobDescriptionId) {
+  try {
+    // Get all current questions
+    const currentQuestions = await behindAPI.easyjob.V10.jobDescriptionCandidateQuestions.getList(jobDescriptionId);
+    
+    // Delete questions with weight less than 5
+    for (const question of currentQuestions.data) {
+      if (question.weight < 5) {
+        await behindAPI.easyjob.V10.jobDescriptionCandidateQuestions.delete(question.question_id);
+        console.log(`Deleted low-weight question: ${question.question}`);
+      }
+    }
+
+    // Get updated list
+    const updatedQuestions = await behindAPI.easyjob.V10.jobDescriptionCandidateQuestions.getList(jobDescriptionId);
+    console.log(`Remaining questions: ${updatedQuestions.data.length}`);
+    
+  } catch (error) {
+    console.error("Error managing questions:", error);
+  }
+}
+```
+
+---
+
+## Best Practices
+
+1. **Question Weight Strategy**: Use a consistent weighting system (e.g., 1-10 scale) where higher weights indicate more critical questions for the position.
+
+2. **Category Organization**:
+    - Use "basic" for fundamental screening questions that apply to most positions
+    - Use "custom" for job-specific questions tailored to the particular role
+    - Note that "general" category is only available for filtering existing questions, not for creating new ones
+    - Use `getByCategory()` to filter questions by their assigned categories
+
+3. **Question Types**:
+    - Use "binary_check" for qualification requirements
+    - Use "integer" for quantifiable experience questions
+    - Use "short_answer" for brief descriptive responses
+    - Use "open_response" for detailed explanations
+
+4. **Error Handling**: Always check the `success` property in responses before proceeding with dependent operations.
+
+5. **Bulk Operations**: When creating multiple questions, consider implementing retry logic and proper error handling for each individual creation.
+
+6. **Parameter Validation**: Ensure question types match the accepted values and weights are positive integers. Remember that category is now required for creation.
+
+---
+
+## API Method Summary
+
+| Method | Purpose | Required Parameters | Optional Parameters |
+|--------|---------|-------------------|-------------------|
+| `create` | Create new question | `jobDescriptionId`, `question`, `type`, `weight`, `category` | None |
+| `delete` | Delete specific question | `questionId` | None |
+| `deleteAll` | Delete all questions for job | `jobDescriptionId` | None |
+| `getList` | Get all questions for job | `jobDescriptionId` | None |
+| `getByCategory` | Get questions by category | `jobDescriptionId`, `category` | None |
+| `edit` | Update existing question | `questionId` | `text`, `weight` |